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 withMaxwellianFluidModel.MHD (
model_options=["MHDModel"]): a single MHD fluid. Set up withMHDModel.
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
MHDModelinstead.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 (seeSimulation) 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).
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), useMaxwellianFluidModelinstead - 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.