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”.

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

  • 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

    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 allocate_helpers(verbose: bool = False)[source]#

Allocate helper arrays and perform initial solves if needed.

property is_default#
forced_heading_level = 5#
classmethod info()[source]#
classmethod pde()[source]#
classmethod normalization()[source]#
classmethod scalar_quantities()[source]#
classmethod discretization()[source]#
classmethod long_description()[source]#
classmethod examples()[source]#
classmethod use_cases()[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, verbose=False)[source]#

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

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” and “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() → dict[source]#

Serialize the model configuration to a dictionary.

classmethod from_dict(dct) → StruphyModel[source]#

Deserialize a model configuration from a dictionary.

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 prop_list#

List of Propagator objects.

property base_units: BaseUnits#

Base units of the model.

property units: Units#

Units of the model.