Models

PHARE runs one of two, independent simulation types, chosen with Simulation(model_options=...):

  • Hybrid (default, model_options=["HybridModel"]): kinetic ions, fluid electrons. Set up with MaxwellianFluidModel.

  • MHD (model_options=["MHDModel"]): a single MHD fluid. Set up with MHDModel.

There is currently no way to combine both in the same run (e.g. MHD on coarse levels and Hybrid on fine levels) - pick one.

Hybrid: MaxwellianFluidModel

The typical way to initialize a Hybrid simulation is to parametrize each ion population by its fluid moments (density, bulk velocity, thermal velocity), assuming an underlying Maxwellian velocity distribution. MaxwellianFluidModel also sets the magnetic field profile.

class pyphare.pharein.MaxwellianFluidModel(bx=None, by=None, bz=None, **kwargs)[source]

MaxwellianFluidModel sets up the Hybrid simulation type: the magnetic field profile and one or more ion populations, each assumed to locally follow a Maxwellian velocity distribution described by its density, bulk velocity and thermal velocity moments. Every population is loaded as macro-particles from these moments; the resulting particles are pushed kinetically while the field is advanced from the fluid electron/Ohm’s law closure set by ElectronModel.

Used for a Hybrid simulation (the default model_options). For an MHD simulation, use MHDModel instead.

Usage example:

ph.MaxwellianFluidModel(
    bx=bx,
    by=by,
    bz=bz,
    protons={"charge": 1,
             "density": density,
             "vbulkx": vx,
             "vbulky": vy,
             "vbulkz": vz,
             "vthx": vthx,
             "vthy": vthy,
             "vthz": vthz,
             "nbr_part_per_cell": 100},

    beam={"charge": 1,
             "density": beam_density,
             "vbulkx": vx_beam,
             "vbulky": vy_beam,
             "vbulkz": vz_beam,
             "vthx": vthx_beam,
             "vthy": vthy_beam,
             "vthz": vthz_beam,
             "nbr_part_per_cell": 500}
)

Magnetic field parameters:

  • bx (function): magnetic field in x direction

  • by (function): magnetic field in y direction

  • bz (function): magnetic field in z direction

Each of bx, by, bz is a function of the spatial coordinates (one argument per dimension: f(x), f(x, y) or f(x, y, z)), or a plain number for a spatially uniform component (default: bx=1, by=bz=0).

Ion populations:

Every other keyword argument names one ion population; its value is a dict of that population’s parameters, all accepted by add_population:

  • charge (float), default=1, electric charge of one particle of this population.

  • mass (float), default=1, mass of one particle of this population.

  • density (function or number), default=1, particle density profile.

  • vbulkx, vbulky, vbulkz (function or number), default=0, bulk velocity profile, per direction.

  • vthx, vthy, vthz (function or number), default=1, thermal velocity profile, per direction.

  • nbr_part_per_cell (int), default=100, number of macro-particles loaded per cell for this population.

  • density_cut_off (float), default=1e-16, cells where density evaluates below this value are not populated with particles.

  • init (dict), optional {"seed": <int>} to fix the random seed used to draw this population’s particle positions/velocities (default: unseeded, i.e. different particles on every run). Each cell draws from its own stream, keyed by the seed, the population name and the cell, so a seeded run gives the same particles whatever the patch layout or number of MPI ranks (for a given compiler and standard library). Two populations with the same seed still get different particles, and renaming a population changes its particles.

All profile functions (density, vbulk*, vth*, and bx/by/bz above) take the spatial coordinates as arguments and must return a value (or an array of values, when called with array coordinates) of the same shape.

Periodicity check: when the domain is periodic (the default), every profile function above is checked for periodicity at construction time. A profile that isn’t actually periodic prints a warning; if Simulation(strict=True) was set, it raises instead. This check is skipped for dry_run (see Simulation) simulations and when restarting.

add_population(name, charge=1.0, mass=1.0, nbr_part_per_cell=100, density=None, vbulkx=None, vbulky=None, vbulkz=None, vthx=None, vthy=None, vthz=None, init=None, density_cut_off=1e-16)[source]

Add an ion population, named name, to this model.

This is what the population dicts passed to MaxwellianFluidModel’s constructor (e.g. protons={…}) are forwarded to; see the class docstring for the full parameter list (charge, mass, density, vbulkx/y/z, vthx/y/z, nbr_part_per_cell, density_cut_off, init).

nbr_populations()[source]

returns the number of species currently registered in the model

Below, a single population of protons:

import pyphare.pharein as ph

ph.MaxwellianFluidModel(
    bx=bx,
    by=by,
    bz=bz,
    protons={"charge": 1,
             "density": density,
             "vbulkx": vx,
             "vbulky": vy,
             "vbulkz": vz,
             "vthx": vthx,
             "vthy": vthy,
             "vthz": vthz,
             "nbr_part_per_cell": 100}
)

density, vbulk*, vthx/y/z and bx/by/bz are each either a plain number (for a spatially uniform value) or a function of the spatial coordinates. For example, the density below defines two current sheets at \(y=0.3L_y\) and \(y=0.7L_y\), each of half-width 0.5:

import numpy as np

def density(x, y):
    # assume `sim` is the Simulation created earlier
    L = sim.simulation_domain()[1]
    return (
        0.2
        + 1.0 / np.cosh((y - L * 0.3) / 0.5) ** 2
        + 1.0 / np.cosh((y - L * 0.7) / 0.5) ** 2
    )

and a corresponding sheared magnetic field profile:

def S(y, y0, l):
    return 0.5 * (1.0 + np.tanh((y - y0) / l))

def bx(x, y):
    Ly = sim.simulation_domain()[1]
    v1, v2 = -1.0, 1.0
    return v1 + (v2 - v1) * (S(y, Ly * 0.3, 0.5) - S(y, Ly * 0.7, 0.5))

Since these are plain Python functions, they can be as complex as needed (here bx calls the helper S).

Adding a second population (e.g. a lower-density beam) is done the same way, under a different keyword:

ph.MaxwellianFluidModel(
    bx=bx, by=by, bz=bz,
    protons={"charge": 1, "density": density,
             "vbulkx": vx, "vbulky": vy, "vbulkz": vz,
             "vthx": vthx, "vthy": vthy, "vthz": vthz,
             "nbr_part_per_cell": 100},
    beam={"charge": 1, "density": beam_density,
          "vbulkx": vx_beam, "vbulky": vy_beam, "vbulkz": vz_beam,
          "vthx": vthx_beam, "vthy": vthy_beam, "vthz": vthz_beam,
          "nbr_part_per_cell": 500},
)

Examples:

  • tests/functional/harris/harris_2d.py - one population.

  • tests/functional/ionIonBeam/ion_ion_beam1d.py - two populations.

A Hybrid simulation also requires an ElectronModel block, see below.

Hybrid: ElectronModel

In a Hybrid simulation, ions are kinetic but electrons are a fluid: their momentum equation (via a chosen pressure closure) is used to compute the electric field, assuming quasineutrality. ElectronModel sets that closure, and is required in every Hybrid simulation.

class pyphare.pharein.ElectronModel(**kwargs)[source]

ElectronModel sets the closure used to compute the fluid electron pressure in a Hybrid simulation (kinetic ions, fluid electrons). This pressure enters the generalized Ohm’s law used to advance the electric field. Required in every Hybrid simulation.

Usage example:

import pyphare.pharein as ph

ph.ElectronModel(closure="isothermal", Te=0.2)

Parameters:

  • closure (str), currently only “isothermal” is implemented.

  • Te (float), default=0.1, electron temperature. With the isothermal closure, this temperature is constant in both space and time, and the electron pressure is simply Te times the electron density.

import pyphare.pharein as ph

ph.ElectronModel(closure="isothermal", Te=0.2)

Not needed for an MHD simulation.

MHD: MHDModel

class pyphare.pharein.MHDModel(density=None, vx=None, vy=None, vz=None, bx=None, by=None, bz=None, p=None)[source]

MHDModel sets up the MHD simulation type: the initial density, velocity, magnetic field and pressure profiles of the single MHD fluid.

Used for an MHD simulation, i.e. one declared with Simulation(model_options=["MHDModel"], ...). For a Hybrid simulation (the default), use MaxwellianFluidModel instead - PHARE runs either Hybrid or MHD, never both together in the same run.

Usage example:

ph.MHDModel(
    density=density,
    vx=vx, vy=vy, vz=vz,
    bx=bx, by=by, bz=bz,
    p=pressure,
)

Parameters:

  • density (function or number), default=1, mass density profile.

  • vx, vy, vz (function or number), default=(1, 0, 0), velocity profile, per direction.

  • bx, by, bz (function or number), default=(1, 0, 0), magnetic field profile, per direction.

  • p (function or number), default=1, thermal pressure profile.

Each parameter is a function of the spatial coordinates (one argument per dimension: f(x), f(x, y) or f(x, y, z)), or a plain number for a spatially uniform value.

sim = ph.Simulation(
    # ...
    model_options=["MHDModel"],
    max_mhd_level=sim_max_nbr_levels,  # every level is MHD
    gamma=5.0 / 3.0,
    reconstruction="Linear",
    limiter="VanLeer",
    riemann="Rusanov",
    mhd_timestepper="TVDRK2",
)

ph.MHDModel(
    density=density,
    vx=vx, vy=vy, vz=vz,
    bx=bx, by=by, bz=bz,
    p=pressure,
)

Examples: tests/functional/mhd_harris/harris.py, tests/functional/mhd_orszagtang/orszag_tang.py, tests/functional/mhd_rotor/rotor.py.