Struphy

Simulation workflow

Building a simulation

A Struphy calculation is defined by a Simulation instance that couples a physical model to a mapped domain, an equilibrium, a spatial discretization and a time-integration scheme. Runtime and output parameters are specified by the same Python interface, making the complete numerical configuration explicit and reproducible.

Simulation configuration

The constructor arguments are grouped below by their role in the physical and numerical formulation. The associated catalogues document 36 models, 44 propagators, and the available domains, equilibria, perturbations and distribution-function backgrounds.

Physical model

The governing system, including its species, dynamical variables and propagators.

modelStruphyModelrequired

Physics model that provides species, propagators and variables.

Browse Models →

Geometry and equilibrium

The mapped computational domain, equilibrium state and tensor-product mesh.

domainDomain= Cuboid()

Computational domain description.

Browse Domains →
equilFluidEquilibrium= None

Initial fluid equilibrium (may be None).

Browse Equilibria →
gridgrids.TensorProductGrid= TensorProductGrid()

Spatial grid used for FEEC variables.

Browse FEEC basics →

num_elements · mpi_dims_mask

Spatial discretization

Spline degrees, quadrature rules and boundary conditions for the discrete de Rham complex.

derham_optsDerhamOptions= DerhamOptions()

Options for discrete differential operators.

Browse FEEC basics →

degree · bcs · nquads · nquads_proj · polar_splines · local_projectors

Temporal discretization

The integration interval, time step and operator-splitting method.

time_optsTime= Time()

Time-stepping options (dt, Tend, split algorithm, ...).

Browse Time integration →

dt · Tend · split_algo

Execution and data management

Output, restart, parallel execution, logging and performance-instrumentation settings.

envEnvironmentOptions= EnvironmentOptions()

Runtime and output environment options.

out_folders · sim_folder · sim_label · restart · max_runtime · save_step · save_restart · sort_step · num_clones

profiling_optsProfilingOptions= ProfilingOptions()

Options passed to scope-profiler when profiling is active.

file_path · label · use_likwid · use_line_profiler · deactivate_profiling · use_nvtx · use_gpu_timing · gpu_timing_backend · deactivate_file_output · recursive_profile · aggregation_mode · capture_region_source … 17 in total

commMPI.Intracomm= None

MPI communicator for parallel execution. If None, uses MPI.COMM_WORLD.

logging_levelint | None= None

Logging level (e.g., logging.INFO, logging.DEBUG). If None, uses default.

Metadata and provenance

Descriptive metadata and the parameter file recorded with the numerical results.

namestr= ''

Name of the simulation.

descriptionstr= ''

Description of the simulation.

params_pathstr= None

Path to a Python parameter file to save alongside outputs.

Minimal configuration

The following script defines a periodic Maxwell problem with an implicit field update. It uses the same construction sequence as the gallery examples, omitting problem-specific diagnostics and visualization.

from struphy import DerhamOptions, EnvironmentOptions, Simulation, Time
from struphy import domains, grids, perturbations
from struphy.models import Maxwell

# Select the governing system and its time-update algorithm.
model = Maxwell()
model.propagators.maxwell.options = model.propagators.maxwell.Options(algo="implicit")

# Define the mapped domain and tensor-product mesh.
domain = domains.Cuboid(r3=20.0)
grid = grids.TensorProductGrid(num_elements=(1, 1, 128))

# Configure the discrete de Rham sequence.
derham_opts = DerhamOptions(degree=(1, 1, 3))

# Prescribe the initial electric-field perturbation.
model.em_fields.e_field.add_perturbation(perturbations.Noise(amp=0.1, comp=0, seed=123))

# Set the integration interval, step size and splitting method.
time_opts = Time(dt=0.05, Tend=50.0, split_algo="LieTrotter")

# Assemble the physical, numerical and runtime configuration.
sim = Simulation(
    model=model,
    name="Maxwell light-wave dispersion",
    env=EnvironmentOptions(out_folders="runs", sim_folder="maxwell_light_wave"),
    domain=domain,
    grid=grid,
    derham_opts=derham_opts,
    time_opts=time_opts,
)

sim.run(profiling_activated=True)   # allocate operators, integrate and write output
sim.pproc()                         # evaluate FEEC fields on a plotting grid
sim.load_plotting_data()            # load processed data for analysis

Execution sequence

The initialization stages execute once within the profiling region setup: total. The subsequent time loop applies the model propagators and writes diagnostics at the requested output interval. The labels below correspond directly to the regions recorded in Struphy profiling data.

  1. setup: run metadata
  2. setup: data storage
  3. setup: geometry vtk
  4. setup: plasma params
  5. setup: restart
  6. setup: initial diagnostics
  7. setup: hdf5 datasets
  8. model.integrate(dt, split_algo)evaluated once per time step until Tend; the splitting scheme composes the model propagators

The time-integration documentation describes the operator composition. The equations and numerical methods implemented by each operator are given in the propagator catalogue.

Output and post-processing

Numerical fields, particle data, geometry and run parameters are written toout_folders/sim_folder. Profiling data are stored alongside these results when instrumentation is enabled. sim.pproc() evaluates the FEEC representation on a sampling grid, andsim.load_plotting_data() exposes the processed quantities through Struphy's analysis interface.

Complete simulation examples →Struphy user guide ↗