Struphy model base class

class struphy.models.base.StruphyModel

Bases: object

Abstract base class for all Struphy models.

This class defines the interface for plasma simulation models in Struphy. Concrete implementations must specify the model type (Fluid, Kinetic, Hybrid, or Toy), define propagators for time integration, and configure species (field, fluid, particle, and diagnostic). The class provides core functionality for managing species, scalar quantities, time integration, and particle diagnostics.

Variables:

• species (dict) – Dictionary of all species (field, fluid, and particle) in the model.

• field_species (dict) – Dictionary of field species in the model.

• fluid_species (dict) – Dictionary of fluid species in the model.

• particle_species (dict) – Dictionary of particle species in the model.

• diagnostic_species (dict) – Dictionary of diagnostic species in the model.

• scalar_quantities (dict) – Dictionary of scalar quantities to be tracked and saved during simulation.

• prop_list (list) – List of propagator objects controlling time integration.

• clone_config (CloneConfig or None) – Configuration for domain clones if used in parallelization.

• subclasses) (Abstract Methods (must be implemented by)

• ----------------------------------------------------

• model_type (classmethod) – Must return one of “Fluid”, “Kinetic”, “Hybrid”, or “Toy”.

• bulk_species (property) – Must specify the dominant plasma species.

• velocity_scale (property) – Must return velocity scale: “alfvén”, “cyclotron”, “light”, or “thermal”.

• allocate_helpers (method) – Must allocate helper arrays and perform initial solves.

• update_scalar_quantities (method) – Must define update rules for each scalar quantity.

• Propagators (class) – Must define the propagators used for time integration.

• __init__ (method) – Must perform a light-weight initialization of the model.

Notes

All Struphy models must be subclasses of StruphyModel and should be added to struphy/models/ in one of the modules: fluid.py, kinetic.py, hybrid.py, or toy.py.

Time integration is performed by calling the integrate() method with a time step and splitting algorithm (Lie-Trotter or Strang). The model manages the execution of all propagators in sequence to advance the simulation state.

Species management is handled automatically through property caching. Species attributes are discovered at runtime and categorized by type.

Examples

Subclasses should implement:

class MyFluidModel(StruphyModel):
    @classmethod
    def model_type(cls):
        return "Fluid"

    @property
    def bulk_species(self):
        return self.electrons

    @property
    def velocity_scale(self):
        return "thermal"

    def allocate_helpers(self, verbose=False):
        # Initialize helper arrays
        pass

    def update_scalar_quantities(self):
        # Update tracked scalars
        pass

    class Propagators:
        # Define propagators
        pass

abstract classmethod model_type() → Literal['Toy', 'Kinetic', 'Fluid', 'Hybrid']

Model type (Fluid, Kinetic, Hybrid, or Toy)

class Propagators

Bases: object

abstract property bulk_species: Species

Bulk species of the plasma. Must be an attribute of species_static().

abstract property velocity_scale: str

Velocity unit scale of the model. Must be one of “alfvén”, “cyclotron”, “light” or “thermal”.

abstract allocate_helpers(verbose: bool = False)

Allocate helper arrays and perform initial solves if needed.

abstract update_scalar_quantities()

Specify an update rule for each item in scalar_quantities using update_scalar().

property is_default

classmethod info(use_rst=False)

Render a class or docstring in a Jupyter notebook.

This function returns an IPython display object that will render the docstring with proper formatting in Jupyter notebooks.

Parameters:

• cls – Class or function whose docstring to display

• use_rst – If True and __doc_rst__ exists, use that instead of __doc__

Returns:

IPython.display object for rendering in Jupyter

Examples

>>> from struphy.models.maxwell import Maxwell
>>> Maxwell.equations()  # Shows HTML version
>>> Maxwell.equations(use_rst=True)  # Shows RST as Markdown

classmethod name() → str

add_scalar(name: str, variable: PICVariable | SPHVariable | None = None, compute=None, summands=None)

Add a scalar to be saved during the simulation.

Parameters:

• name (str) – Dictionary key for the scalar.

• variable (PICVariable | SPHVariable, optional) – The variable associated with the scalar. Required if compute is ‘from_particles’.

• compute (str, optional) – Type of scalar, determines the compute operations. Options: ‘from_particles’ or ‘from_field’. Default is None.

• summands (list, optional) – List of other scalar names whose values should be summed to compute the value of this scalar. Default is None.

update_scalar(name, value=None)

Update a scalar during the simulation.

Parameters:

• name (str) – Dictionary key of the scalar.

• value (float, optional) – Value to be saved. Required if there are no summands.

print_scalar_quantities()

Check if scalar_quantities are not “nan” and print to screen.

setup_equation_params(units: Units, verbose=False)

Set euqation parameters for each fluid and kinetic species.

integrate(dt, split_algo='LieTrotter')

Advance the model by a time step dt by sequentially calling its Propagators.

Parameters:

• dt (float) – Time step of time integration.

• split_algo (str) – Splitting algorithm. Currently available: “LieTrotter” and “Strang”.

update_markers_to_be_saved()

Writes markers with IDs that are supposed to be saved into corresponding array.

update_distr_functions()

Writes distribution functions slices that are supposed to be saved into corresponding array.

generate_default_parameter_file(path: str | None = None, prompt: bool = True)

Generate a parameter file with default options for each species, and save it to the current input path.

The default name is params_<model_name>.yml.

Parameters:

• path (str) – Alternative path to getcwd()/params_MODEL.py.

• prompt (bool) – Whether to prompt for overwriting the specified .yml file.

Returns:

params_path – The path of the parameter file.

Return type:

str

to_dict() → dict

Serialize the model configuration to a dictionary.

classmethod from_dict(dct) → StruphyModel

Deserialize a model configuration from a dictionary.

classmethod from_name(name: str) → StruphyModel

Instantiate a model from its name.

property field_species: dict

property fluid_species: dict

property particle_species: dict

property diagnostic_species: dict

property species

property clone_config

Config in case domain clones are used.

property prop_list

List of Propagator objects.

property scalar_quantities

A dictionary of scalar quantities to be saved during the simulation.