Adding a new PDE model#

Struphy provides an abstract framework for seamless addition of new model equations. A model consists of a set of PDEs that has been discretized within the GEMPIC framework.

New Struphy models must be added in one of the four modules:

as child classes of the StruphyModel. Please refer to existing models for templates. Here is a list of points that need to be followed when creating a new model:

1. Start from a template#

Perform the following steps:

  1. In one of the four files above, copy-and-paste an existing model.

  2. Change the class name to <newname>.

  3. Run struphy --refresh-models in the console.

  4. Type struphy params <newname> and run the new model.

2. Derive Struphy discretization of your PDE#

Struphy uses the GEMPIC framework on 3D mapped domains. This framework uses Lagrangian particle methods combined with geometric finite elements based on differential forms.

Please consult Example: Vlasov-Maxwell-Poisson discretization and/or given references for a tutorial on how to apply this discretization method.

3. Define Species#

See Species types.

4. Define bulk_species and velocity_scale#

These must be implemented in every Struphy model in order to struphy.io.setup.derive_units(), see also Normalization.

5. Add Propagators#

Propagators are the main building blocks of Models, as they define the time splitting scheme in struphy.models.base.StruphyModel.integrate.

When adding a new model to Struphy, make sure to

  1. check the lists of available propagators - maybe what you need is already there!

  2. write your own propagators based on existing templates.

Propagators are in one of the following modules:

Check out How to write a Propagator for practical details on the implementation.

A model’s propagators are defined in struphy.models.base.StruphyModel.Propagators. The order in which propagators are added in Propagators matters. They are called consecutively according to the time splitting scheme defined in Time stepping parameters.

6. Add scalar quantities#

It is often usefule to define scalar quantities that should be saved during the simulation, e.g. for checking concervation properties. This can be done via the methods

Check out existing models for templates.

7. Overrride generate_default_parameter_file#

If necessary due to the propagators of the model, override struphy.models.base.StruphyModel.generate_default_parameter_file() to generate the parameter file you intended.

8. Test#

Once you added a model and re-installed struphy (pip install -e .), you can run the model with:

struphy params -y <yourmodel>
python params_<yourmodel>.py

If the model is not found:

struphy --refresh-models