Struphy model base class#

class struphy.models.base.StruphyModel[source]#

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, as attributes created in its __init__. The splitting order is the attribute order, unless Propagators defines a tuple splitting_order with the attribute names (as class attribute or in its __init__), see apply_splitting_order().
__init__ (method) – Must perform a light-weight initialization of the model.

Notes

All Struphy models must be subclasses of StruphyModel. Each model lives in its own module struphy/models/<model_name>.py (snake case of the class name). After adding a model, regenerate struphy/models/__init__.py with struphy build-init-files and add the model by hand to struphy/api/models/__init__.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'][source]#: Model type (Fluid, Kinetic, Hybrid, or Toy)

class Propagators[source]#: 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()[source]#: Perform operations after main allocation and before time stepping.

property is_default#

forced_heading_level = 5#

classmethod info_html() → str[source]#

classmethod info_markdown() → str[source]#

classmethod info_latex() → str[source]#

classmethod info()[source]#

classmethod pde_html() → str[source]#

classmethod pde_markdown() → str[source]#

classmethod pde_latex() → str[source]#

classmethod pde()[source]#

classmethod normalization_html() → str[source]#

classmethod normalization_markdown() → str[source]#

classmethod normalization_latex() → str[source]#

classmethod normalization()[source]#

classmethod scalar_quantities_html() → str[source]#

classmethod scalar_quantities_markdown() → str[source]#

classmethod scalar_quantities_latex() → str[source]#

classmethod scalar_quantities()[source]#

classmethod doc_discretization() → str[source]#: Time integration is performed by the following propagators (in sequence):

classmethod propagators_in_splitting_order() → dict[str, Propagator][source]#

The propagators of the model in splitting order, as {attribute name: propagator}.

Propagators is instantiated with its default arguments (light-weight, nothing is allocated).

classmethod propagators_links() → str[source]#: Numbered reST list of the propagator classes of the model in splitting order.

classmethod propagators_doc() → str[source]#: Documentation of the propagators of the model in splitting order: the docstring of doc_discretization() (a model overrides it to describe the time stepping), followed by the docstring of each propagator class.

classmethod discretization_html() → str[source]#

classmethod discretization_markdown() → str[source]#

classmethod discretization_latex() → str[source]#

classmethod discretization()[source]#

classmethod long_description_html() → str[source]#

classmethod long_description_markdown() → str[source]#

classmethod long_description_latex() → str[source]#

classmethod long_description()[source]#

classmethod examples_html() → str[source]#

classmethod examples_markdown() → str[source]#

classmethod examples_latex() → str[source]#

classmethod examples()[source]#

classmethod use_cases_html() → str[source]#

classmethod use_cases_markdown() → str[source]#

classmethod use_cases_latex() → str[source]#

classmethod use_cases()[source]#

classmethod cannot_be_used_for_html() → str[source]#

classmethod cannot_be_used_for_markdown() → str[source]#

classmethod cannot_be_used_for_latex() → str[source]#

classmethod cannot_be_used_for()[source]#

classmethod name() → str[source]#

classmethod create_doc() → Documentation[source]#

property scalars: Scalars | None#: Scalars to be updated and saved during the simulation.

update_scalar_quantities()[source]#: 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()[source]#: Check if scalars are not “nan” and print to screen.

setup_equation_params(base_units: BaseUnits)[source]#: Compute units and set equation parameters for each fluid and kinetic species.

show_equation_params()[source]#: Print the equation parameters for each species to screen.

integrate(dt, split_algo='LieTrotter')[source]#

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” (first order) and “Strang” (second order). The groups in Propagators.strang_groups are integrated symmetrically as one block of the splitting, see splitting_blocks().

propagator_calls(dt: float, split_algo: str = 'LieTrotter') → list[tuple[str, float]][source]#

The propagator calls of one time step of integrate(), as (propagator name, time step) in order.

Parameters:

dt (float) – Time step of time integration.
split_algo (str) – Splitting algorithm, “LieTrotter” or “Strang”.

update_markers_to_be_saved()[source]#: Writes markers with IDs that are supposed to be saved into corresponding array.

update_distr_functions()[source]#: Writes distribution functions slices that are supposed to be saved into corresponding array.

generate_default_parameter_file(path: str | None = None, prompt: bool = True)[source]#

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[source]#

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[source]#: Deserialize a model from to_dict().

classmethod from_name(name: str) → StruphyModel[source]#: 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 propagators#: Instance of the inner class Propagators; its attributes are the propagators in splitting order.

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.

Table of Contents

Previous topic

Next topic

Struphy model base class#