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.

• scalars (Scalars or None) – 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”.

• post_allocate (method) – Must perform operations after main allocation and before time stepping.

• 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 post_allocate(self):
        # Perform operations after main allocation and before time stepping
        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 post_allocate()

Perform operations after main allocation and before time stepping.

property is_default

forced_heading_level = 5

classmethod info_html() → str

classmethod info_markdown() → str

classmethod info_latex() → str

classmethod info()

classmethod pde_html() → str

classmethod pde_markdown() → str

classmethod pde_latex() → str

classmethod pde()

classmethod normalization_html() → str

classmethod normalization_markdown() → str

classmethod normalization_latex() → str

classmethod normalization()

classmethod scalar_quantities_html() → str

classmethod scalar_quantities_markdown() → str

classmethod scalar_quantities_latex() → str

classmethod scalar_quantities()

classmethod discretization_html() → str

classmethod discretization_markdown() → str

classmethod discretization_latex() → str

classmethod discretization()

classmethod long_description_html() → str

classmethod long_description_markdown() → str

classmethod long_description_latex() → str

classmethod long_description()

classmethod examples_html() → str

classmethod examples_markdown() → str

classmethod examples_latex() → str

classmethod examples()

classmethod use_cases_html() → str

classmethod use_cases_markdown() → str

classmethod use_cases_latex() → str

classmethod use_cases()

classmethod cannot_be_used_for_html() → str

classmethod cannot_be_used_for_markdown() → str

classmethod cannot_be_used_for_latex() → str

classmethod cannot_be_used_for()

classmethod name() → str

classmethod create_doc() → Documentation

property scalars: Scalars | None

Scalars to be updated and saved during the simulation.

update_scalar_quantities()

Update scalar quantities by calling their .update() method. This should be called at the end of each time step in the simulation loop.

print_scalar_quantities()

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

setup_equation_params(base_units: BaseUnits)

Compute units and set equation parameters for each fluid and kinetic species.

show_equation_params()

Print the equation parameters for each species to screen.

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(*, initial_condition_serializer=None) → dict

Serialize the model constructor, variables and propagator options.

Pass an initial-condition serializer to include each variable’s definitions in run metadata. The plain configuration omits them.

classmethod from_dict(dct) → StruphyModel

Deserialize a model from to_dict().

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 base_units: BaseUnits

Base units of the model.

property units: Units

Units of the model.

property params: dict

Model parameters passed to __init__() of the class, as dictionary.