Userguide

This guide takes you through the classes used in Struphy launch files generated by:

struphy params MODEL

for a valid MODEL from the list of Models. All information for running simulations are contained and can be altered in such launch (parameter) files. It is recommended to generate such a file and inspect it with an editor like VScode (using a type checker like “mypy”).

Post-processing is discussed at the end of this section.

Basic options

class struphy.io.options.EnvironmentOptions(out_folders: str = '/home/runner/work/struphy/struphy/doc', sim_folder: str = 'sim_1', restart: bool = False, max_runtime: int = 300, save_step: int = 1, sort_step: int = 0, num_clones: int = 1)

Environment options for launching run on current architecture (these options do not influence the simulation result).

Parameters:

• out_folders (str) – Absolute path to directory for sim_folder.

• sim_folder (str) – Folder in out_folders/ for the current simulation (default= sim_1/ ). Will create the folder if it does not exist OR cleans the folder for new runs.

• restart (bool) – Whether to restart a run (default=False).

• max_runtime (int) – Maximum run time of simulation in minutes. Will finish the time integration once this limit is reached (default=300).

• save_step (int) – When to save data output: every time step (save_step=1), every second time step (save_step=2), etc (default=1).

• sort_step (int, optional) – Sort markers in memory every N time steps (default=0, which means markers are sorted only at the start of simulation)

• num_clones (int, optional) – Number of domain clones (default=1)

class struphy.io.options.BaseUnits(x: float = 1.0, B: float = 1.0, n: float = 1.0, kBT: float | None = None)

Base units from which other units are derived. See Normalization.

Parameters:

• x (float) – Unit of length in meters.

• B (float) – Unit of magnetic field in Tesla.

• n (float) – Unit of particle number density in 1e20/m^3.

• kBT (float, optional) – Unit of internal energy in keV. Only in effect if the velocity scale is set to ‘thermal’.

class struphy.io.options.Time(dt: float = 0.01, Tend: float = 0.03, split_algo: Literal['LieTrotter', 'Strang'] = 'LieTrotter')

Time stepping options.

Parameters:

• dt (float) – Time step.

• Tend (float) – End time.

• split_algo (SplitAlgos) – Splitting algorithm (the order of the propagators is defined in the model).

Simulation domains

See Geometry.

Fluid backgrounds

See Available fluid equilibria.

Grids

class struphy.topology.grids.TensorProductGrid(Nel: tuple = (24, 10, 1), mpi_dims_mask: tuple = (True, True, True))

Bases: object

Grid as a tensor product of 1d grids.

Parameters:

• Nel (tuple[int]) – Number of elements in each direction.

• mpi_dims_mask (Tuple of bool) – True if the dimension is to be used in the domain decomposition (=default for each dimension). If mpi_dims_mask[i]=False, the i-th dimension will not be decomposed.

Derham complex

class struphy.io.options.DerhamOptions(p: tuple = (1, 1, 1), spl_kind: tuple = (True, True, True), dirichlet_bc: tuple = ((False, False), (False, False), (False, False)), nquads: tuple | None = None, nq_pr: tuple | None = None, polar_ck: Literal[-1, 1] = -1, local_projectors: bool = False)

Options for the Derham spaces. See Geometric finite elements (FEEC).

Parameters:

• p (tuple[int]) – Spline degree in each direction.

• spl_kind (tuple[bool]) – Kind of spline in each direction (True=periodic, False=clamped).

• dirichlet_bc (tuple[tuple[bool]]) – Whether to apply homogeneous Dirichlet boundary conditions (at left or right boundary in each direction).

• nquads (tuple[int]) – Number of Gauss-Legendre quadrature points in each direction (default = p, leads to exact integration of degree 2p-1 polynomials).

• nq_pr (tuple[int]) – Number of Gauss-Legendre quadrature points in each direction for geometric projectors (default = p+1, leads to exact integration of degree 2p+1 polynomials).

• polar_ck (PolarRegularity) – Smoothness at a polar singularity at eta_1=0 (default -1 : standard tensor product splines, OR 1 : C1 polar splines)

• local_projectors (bool) – Whether to build the local commuting projectors based on quasi-inter-/histopolation.

Models

See Models.

Species types

Each Struphy model is a collection of species of one of the following types:

class struphy.models.species.FieldSpecies

Species without mass and charge (so-called ‘fields’).

class struphy.models.species.FluidSpecies

Single fluid species in 3d configuration space.

class struphy.models.species.ParticleSpecies

Single kinetic species in 3d + vdim phase space.

Species.set_phys_params(charge_number: int = 1, mass_number: int = 1, alpha: float | None = None, epsilon: float | None = None, kappa: float | None = None)

Set charge- and mass number of species. Optional: Set equation parameters (alpha, epsilon, kappa) to override units.

Variable types

Each species can contain multiple variables.

class struphy.models.variables.PICVariable(space: Literal['Particles6D', 'DeltaFParticles6D', 'Particles5D', 'Particles3D'] = 'Particles6D')

Variable discretized with Particle-in-cell methods (PIC).

class struphy.models.variables.FEECVariable(space: Literal['H1', 'Hcurl', 'Hdiv', 'L2', 'H1vec'] = 'H1')

Variable discretized with Geometric finite elements (FEEC).

class struphy.models.variables.SPHVariable

Variable discretized with Smoothed particle hydrodynamics (SPH).

Setting particle parameters

class struphy.pic.utilities.LoadingParameters(Np: int | None = None, ppc: int | None = None, ppb: int = 10, loading: Literal['pseudo_random', 'sobol_standard', 'sobol_antithetic', 'external', 'restart', 'tesselation'] = 'pseudo_random', seed: int | None = None, moments: tuple | None = None, spatial: Literal['uniform', 'disc'] = 'uniform', specific_markers: tuple[tuple] | None = None, n_quad: int = 1, dir_exrernal: str | None = None, dir_particles: str | None = None, dir_particles_abs: str | None = None, restart_key: str | None = None)

Parameters for particle loading.

Parameters:

• Np (int) – Total number of particles to load.

• ppc (int) – Particles to load per cell if a grid is defined. Cells are defined from domain_array.

• ppb (int) – Particles to load per sorting box. Sorting boxes are defined from boxes_per_dim.

• loading (OptsLoading) – How to load markers: multiple options for Monte-Carlo, or “tesselation” for positioning them on a regular grid.

• seed (int) – Seed for random generator. If None, no seed is taken.

• moments (tuple) – Mean velocities and temperatures for the Gaussian sampling distribution. If None, these are auto-calculated form the given background.

• spatial (OptsSpatialLoading) – Draw uniformly in eta, or draw uniformly on the “disc” image of (eta1, eta2).

• specific_markers (tuple[tuple]) – Each entry is a tuple of phase space coordinates (floats) of a specific marker to be initialized.

• n_quad (int) – Number of quadrature points for tesselation.

• dir_external (str) – Load markers from external .hdf5 file (absolute path).

• dir_particles_abs (str) – Load markers from restart .hdf5 file (absolute path).

• dir_particles (str) – Load markers from restart .hdf5 file (relative path to output folder).

• restart_key (str) – Key in .hdf5 file’s restart/ folder where marker array is stored.

class struphy.pic.utilities.WeightsParameters(control_variate: bool = False, reject_weights: bool = False, threshold: float = 0.0)

Paramters for particle weights.

Parameters:

• control_variate (bool) – Whether to use a control variate for noise reduction.

• reject_weights (bool) – Whether to reject weights below threshold.

• threshold (float) – Threshold for rejecting weights.

class struphy.pic.utilities.BoundaryParameters(bc: tuple[Literal['periodic', 'reflect']] = ('periodic', 'periodic', 'periodic'), bc_refill=None, bc_sph: tuple[Literal['periodic', 'mirror', 'fixed']] = ('periodic', 'periodic', 'periodic'))

Parameters for particle boundary and sph reconstruction boundary conditions.

Parameters:

• bc (tuple[OptsMarkerBC]) – Boundary conditions for particle movement. Either ‘remove’, ‘reflect’, ‘periodic’ or ‘refill’ in each direction.

• bc_refill (list) – Either ‘inner’ or ‘outer’.

• bc_sph (tuple[OptsRecontructBC]) – Boundary conditions for sph kernel reconstruction.

class struphy.pic.utilities.BinningPlot(slice: str = 'e1', n_bins: int | tuple[int] = 128, ranges: tuple[float] | tuple[tuple[float]] = (0.0, 1.0), divide_by_jac: bool = True)

Binning plot of marker distribution in phase space.

Parameters:

• slice (str) – Coordinate-slice in phase space to bin. A combination of “e1”, “e2”, “e3”, “v1”, etc., separated by an underscore “_”. For example, “e1” showas a 1D binning plot over eta1, whereas “e1_v1” shows a 2D binning plot over eta1 and v1.

• n_bins (int | tuple[int]) – Number of bins for each coordinate.

• ranges (tuple[int] | tuple[tuple[int]] = (0.0, 1.0)) – Binning range (as an interval in R) for each coordinate.

• divide_by_jac (bool) – Whether to divide by the Jacobian determinant (volume-to-0-form).

class struphy.pic.utilities.KernelDensityPlot(pts_e1: int = 16, pts_e2: int = 16, pts_e3: int = 1)

SPH density plot in configuration space.

Parameters:

• pts_e1 (int) – Number of evaluation points in each direction.

• pts_e2 (int) – Number of evaluation points in each direction.

• pts_e3 (int) – Number of evaluation points in each direction.

Setting backgrounds

FEECVariable.add_background(background: FieldsBackground, verbose=True)

Add a static background for this variable. Multiple backgrounds can be added up.

PICVariable.add_background(background: KineticBackground, n_as_volume_form: bool = False, verbose=True)

Add a static background for this variable. Multiple backgrounds can be added up.

SPHVariable.add_background(background: FluidEquilibrium, verbose=True)

Add a static background for this variable. Multiple backgrounds can be added up.

class struphy.io.options.FieldsBackground(type: Literal['LogicalConst', 'FluidEquilibrium'] = 'LogicalConst', values: tuple = (1.5, 0.7, 2.4), variable: str | None = None)

Options for backgrounds in configuration (=position) space.

Parameters:

• type (BackgroundTypes) – Type of background.

• values (tuple[float]) – Values for LogicalConst on the unit cube. Can be length 1 for scalar functions; must be length 3 for vector-valued functions.

• variable (str) – Name of the method in FluidEquilibrium that should be the background.

Adding perturbations

FEECVariable.add_perturbation(perturbation: Perturbation, verbose=True)

Add an initial Perturbation for this variable. Multiple perturbations can be added up.

SPHVariable.add_perturbation(del_n: Perturbation | None = None, del_u1: Perturbation | None = None, del_u2: Perturbation | None = None, del_u3: Perturbation | None = None, verbose=True)

Add an initial Perturbation for the fluid density and/or velocity.

class struphy.initial.base.Perturbation

Base class for perturbations that can be chosen as initial conditions.

See available Perturbation functions.

Setting initial conditions

PICVariable.add_initial_condition(init: KineticBackground, verbose=True)

For FEECVariable and SPHVariable the initial condition is automatically created as the sum of background + perturbation.

Post-processing

struphy.main.pproc(path: str, *, step: int = 1, celldivide: int = 1, physical: bool = False, guiding_center: bool = False, classify: bool = False, no_vtk: bool = False, time_trace: bool = False)

Post-processing finished Struphy runs.

Parameters:

• path (str) – Absolute path of simulation output folder to post-process.

• step (int) – Whether to do post-processing at every time step (step=1, default), every second time step (step=2), etc.

• celldivide (int) – Grid refinement in evaluation of FEM fields. E.g. celldivide=2 evaluates two points per grid cell.

• physical (bool) – Wether to do post-processing into push-forwarded physical (xyz) components of fields.

• guiding_center (bool) – Compute guiding-center coordinates (only from Particles6D).

• classify (bool) – Classify guiding-center trajectories (passing, trapped or lost).

• no_vtk (bool) – whether vtk files creation should be skipped

• time_trace (bool) – whether to plot the time trace of each measured region

class struphy.main.SimData(path: str)

Holds post-processed Struphy data as attributes.

Parameters:

path (str) – Absolute path of simulation output folder to post-process.

property orbits: dict[str, ndarray]

3d arrays indexed by (n, p, a), where ‘n’ is the time index, ‘p’ the particle index and ‘a’ the attribute index.

Type:

Keys

Type:

species name. Values

property f: dict[str, dict[str, dict[str, ndarray]]]

dicts of slice names (‘e1_v1’ etc.) holding dicts of corresponding xp.arrays for plotting.

Type:

Keys

Type:

species name. Values

property spline_values: dict[str, dict[str, ndarray]]

dicts of variable names with values being 3d arrays on the grid.

Type:

Keys

Type:

species name. Values

property n_sph: dict[str, dict[str, dict[str, ndarray]]]

dicts of view names (‘view_0’ etc.) holding dicts of corresponding xp.arrays for plotting.

Type:

Keys

Type:

species name. Values

property Nt: dict[str, int]

Number of available time points (snap shots) for each species.

property Np: dict[str, int]

Number of particle orbits for each species.

property Nattr: dict[str, int]

Number of particle attributes for each species.

struphy.main.load_data(path: str) → SimData

Load data generated during post-processing.

Parameters:

path (str) – Absolute path of simulation output folder to post-process.