import os
from copy import deepcopy
import numpy as np
from ..core import box as boxm
from ..core import phare_utilities
from ..core.box import Box
from . import boundary, global_vars, timestepper
# ------------------------------------------------------------------------------
def supported_dimensions():
return [1, 2, 3]
def compute_dimension(cells):
return len(cells)
# ------------------------------------------------------------------------------
def de_numpify_recursive(owner, key):
obj = getattr(owner, key)
if obj is None:
return
if isinstance(obj, np.ndarray):
object.__setattr__(owner, key, obj.tolist())
elif hasattr(obj, "__dict__"):
for k in obj.__dict__:
de_numpify_recursive(obj, k)
def de_numpify_simulation(sim):
assert isinstance(sim, Simulation)
for k in sim.__dict__:
de_numpify_recursive(sim, k)
return sim
def re_numpify_recursive(owner, key):
obj = getattr(owner, key)
if obj is None:
return
if isinstance(obj, list) and len(obj) and not isinstance(obj[0], str):
object.__setattr__(owner, key, np.array(obj))
elif hasattr(obj, "__dict__"):
for k in obj.__dict__:
re_numpify_recursive(obj, k)
def re_numpify_simulation(sim):
assert isinstance(sim, Simulation)
for k in sim.__dict__:
re_numpify_recursive(sim, k)
return sim
def check_domain(**kwargs):
"""
check parameters relative to the domain and raise exceptions if they are not valid
return 'dl' and 'cells'
"""
dom_and_dl = "domain_size" in kwargs and "dl" in kwargs and "cells" not in kwargs
cells_and_dl = "cells" in kwargs and "dl" in kwargs and "domain_size" not in kwargs
dom_and_cells = "cells" in kwargs and "domain_size" in kwargs and "dl" not in kwargs
if not (dom_and_dl or dom_and_cells or cells_and_dl):
raise ValueError(
"Error: Specify either 'domain_size' and 'dl' or 'cells' and 'dl' or 'domain_size' and 'dl'"
)
if dom_and_dl:
try:
phare_utilities.check_iterables(kwargs["domain_size"], kwargs["dl"])
phare_utilities.check_equal_size(kwargs["domain_size"], kwargs["dl"])
except ValueError as e:
raise ValueError(
"Error: 'domain_size' and 'dl' must have the same dimension"
) from e
domain_size = phare_utilities.listify(kwargs["domain_size"])
dl = phare_utilities.listify(kwargs["dl"])
cells = [
int(dom_size / float(mesh_size))
for dom_size, mesh_size in zip(domain_size, dl)
]
for s, d in zip(domain_size, dl):
if s < d:
raise ValueError("Error: mesh size should be smaller than domain_size")
dl = [dom_size / n for dom_size, n in zip(domain_size, cells)]
elif cells_and_dl:
try:
phare_utilities.check_iterables(kwargs["cells"], kwargs["dl"])
phare_utilities.check_equal_size(kwargs["cells"], kwargs["dl"])
except ValueError as e:
raise ValueError(
"Error: 'cells' and 'dl' must have the same dimension"
f" ({kwargs['cells']} and {kwargs['dl']})"
) from e
dl = phare_utilities.listify(kwargs["dl"])
cells = phare_utilities.listify(kwargs["cells"])
elif dom_and_cells:
try:
phare_utilities.check_iterables(kwargs["cells"], kwargs["domain_size"])
phare_utilities.check_equal_size(kwargs["cells"], kwargs["domain_size"])
except ValueError as e:
raise ValueError(
"Error: 'cells' and 'domain_size' must have the same dimension"
) from e
cells = phare_utilities.listify(kwargs["cells"])
domain_size = phare_utilities.listify(kwargs["domain_size"])
dl = [dom_size / float(n) for dom_size, n in zip(domain_size, cells)]
for n, d in zip(cells, dl):
if n != 0 and n < 10:
raise ValueError(
"Error: number of cells in non-invariant directions should be >= 10"
)
if n == 0 and d != 0:
raise ValueError("Error: dl should be 0 for invariant directions")
if n < 0:
raise ValueError("Error: number of cells must be >= 0")
if d < 0:
raise ValueError("Error: mesh size must be >= 0")
return dl, cells
# ------------------------------------------------------------------------------
valid_interp_orders = [1, 2, 3]
# A run with no hybrid model has no interpolation order: clients say so by omitting
# interp_order (or passing None). 0 is only the internal value we ship to C++, where
# SimOpts::interp_order needs an integer and derives hybrid_enabled from it being > 0.
no_hybrid_interp_order = 0
def hybrid_is_active(interp_order):
"""interp_order is how a run says whether it has a hybrid model at all:
C++ SimOpts derives hybrid_enabled from it the same way."""
return interp_order != no_hybrid_interp_order
def check_interp_order(**kwargs):
model_options = phare_utilities.listify(kwargs.get("model_options", "HybridModel"))
interp_order = kwargs.get("interp_order")
if interp_order is None:
return 1 if "HybridModel" in model_options else no_hybrid_interp_order
if interp_order not in valid_interp_orders:
raise ValueError(
f"Error: invalid interpolation order ({interp_order}), should be in "
f"{valid_interp_orders}; omit it for a run with no hybrid model"
)
return interp_order
# ------------------------------------------------------------------------------
def check_pusher(**kwargs):
pusher = kwargs.get("particle_pusher", "modified_boris")
if pusher not in ["modified_boris"]:
raise ValueError(f"Error: invalid pusher ({pusher})")
return pusher
# ------------------------------------------------------------------------------
def check_layout(**kwargs):
layout = kwargs.get("layout", "yee")
if layout not in ("yee"):
raise ValueError(f"Error: invalid layout ({layout})")
return layout
# ------------------------------------------------------------------------------
def check_path(**kwargs):
path = kwargs.get("path", "." + os.path.sep)
return path
# ------------------------------------------------------------------------------
# See: https://github.com/PHAREHUB/PHARE/wiki/exactSplitting
# This should match possibleSimulators() in meta_utilities.h
valid_refined_particle_nbr = {
# dim : {interp : [valid list refined_particle_nbr]}
1: {1: [2, 3], 2: [2, 3, 4], 3: [2, 3, 4, 5]},
2: {1: [4, 5, 8, 9], 2: [4, 5, 8, 9, 16], 3: [4, 5, 8, 9, 25]},
3: {
1: [6, 7, 8, 9, 12, 13, 14, 15, 18, 19, 20, 21, 26, 27],
2: [6, 7, 8, 9, 12, 13, 14, 15, 18, 19, 20, 21, 26, 27, 64],
3: [6, 7, 8, 9, 12, 13, 14, 15, 18, 19, 20, 21, 26, 27, 125],
},
} # Default refined_particle_nbr per dim/interp is considered index 0 of list
no_refined_particle_nbr = (
0 # internal, C++-facing counterpart of no_hybrid_interp_order
)
def check_refined_particle_nbr(ndim, **kwargs):
interp = kwargs["interp_order"]
refined_particle_nbr = kwargs.get("refined_particle_nbr")
# like interp_order, a run with no hybrid model has no refined particle number, and
# says so by omitting the key. 0 is again only what C++ SimOpts is given.
if not hybrid_is_active(interp):
if refined_particle_nbr is not None:
raise ValueError(
"Error: refined_particle_nbr is meaningless without a hybrid model "
"(no interp_order given), it should be omitted"
)
return no_refined_particle_nbr
if refined_particle_nbr is None:
refined_particle_nbr = valid_refined_particle_nbr[ndim][interp][0]
if refined_particle_nbr not in valid_refined_particle_nbr[ndim][interp]:
raise ValueError(
f"Invalid split particle number, valid values for dim({ndim}) "
+ f"interp({interp}) include {valid_refined_particle_nbr[ndim][interp]}"
)
return refined_particle_nbr
# ------------------------------------------------------------------------------
def as_list_per_level(refinement_boxes):
"""
accepts various formats of boxes.
returns {"L0" : [Box(),Box()]}
"""
list_per_level = {}
for level_key, boxes in refinement_boxes.items():
if isinstance(level_key, str):
assert level_key[0] == "L"
else:
level_key = "L" + str(level_key)
if isinstance(boxes, list) and all(isinstance(box, Box) for box in boxes):
list_per_level[level_key] = boxes
elif isinstance(boxes, dict):
list_per_level[level_key] = []
if all(isinstance(val, Box) for key, val in boxes.items()):
for box in boxes.values():
list_per_level[level_key] += [box]
elif all(isinstance(val, (tuple, list)) for key, val in boxes.items()):
for box_coords in boxes.values():
box_coords = [list(box_coord) for box_coord in box_coords]
list_per_level[level_key] += [Box(box_coords[0], box_coords[1])]
return list_per_level
def check_refinement_boxes(ndim, **kwargs):
"""
returns tuple ( { "L0" : [Boxes]}, max_nbr_levels)
"""
refinement_boxes = kwargs.get("refinement_boxes")
if (
refinement_boxes is None or len(refinement_boxes) == 0
): # SAMRAI errors if empty dict
return None, 1 # default max level number to 1 if no boxes
smallest_patch_size = kwargs.get("smallest_patch_size")
refinement_ratio = kwargs["refinement_ratio"]
nesting_buffer = kwargs["nesting_buffer"]
refinement_boxes = as_list_per_level(refinement_boxes)
domain_box = Box([0] * ndim, np.asarray(kwargs["cells"]) - 1)
boxes_per_level = {0: [domain_box]}
for level_key, boxes in refinement_boxes.items():
ilvl = int(level_key[1:])
refined_level_number = ilvl + 1
boxes_per_level[refined_level_number] = [
boxm.refine(box, refinement_ratio) for box in boxes
]
if len(boxes) == 0:
raise ValueError("Error - missing refinement boxes")
for box_idx, ref_box in enumerate(boxes):
for cmp_box in boxes[box_idx + 1 :]:
if ref_box * cmp_box is not None:
raise ValueError(
f"Error: Box({ref_box}) overlaps with Box({cmp_box})"
)
for box in boxes:
refined_coarser_boxes = boxes_per_level[ilvl]
coarse_nCell = 0
for refined_coarser in refined_coarser_boxes:
intersection = box * boxm.shrink(refined_coarser, nesting_buffer)
coarse_nCell += 0 if intersection is None else intersection.nCells()
if coarse_nCell != box.nCells():
raise ValueError(
f"Box({box}) is incompatible with coarser boxes({refined_coarser_boxes}) and nest_buffer({nesting_buffer})"
)
if box.ndim != ndim:
raise ValueError(f"Box({box}) has incorrect dimensions for simulation")
for length in boxm.refine(box, refinement_ratio).shape:
if (length < smallest_patch_size).any():
raise ValueError(
"Invalid box incompatible with smallest_patch_size"
)
return refinement_boxes, len(refinement_boxes.items()) + 1
# ------------------------------------------------------------------------------
def check_patch_size(ndim, **kwargs):
interp = kwargs["interp_order"]
small_invalid_patch_size = 2
smallest_patch_size = small_invalid_patch_size + 1
smallest_patch_size = phare_utilities.np_array_ify(smallest_patch_size, ndim)
if "smallest_patch_size" in kwargs and kwargs["smallest_patch_size"] is not None:
smallest_patch_size = phare_utilities.np_array_ify(
kwargs["smallest_patch_size"], ndim
)
if interp == 1 and any(v == 4 or v == 5 for v in smallest_patch_size):
samrai_bug_url = "https://github.com/llnl/SAMRAI/issues/311"
raise ValueError(
f"Error: smallest_patch_size cannot be 4 or 5 in interp 1 because of {samrai_bug_url}"
)
cells = phare_utilities.np_array_ify(kwargs["cells"])
if smallest_patch_size.size != ndim:
raise ValueError(
f"Error: smallest_patch_size({smallest_patch_size.size}) must be size {ndim}"
)
if (smallest_patch_size <= small_invalid_patch_size).any():
raise ValueError(
"Error - smallest_patch_size cannot be <= " + str(small_invalid_patch_size)
)
if (smallest_patch_size > cells).any():
raise ValueError(
"Error - smallest_patch_size should be less than nbr of cells in all directions"
)
largest_patch_size = kwargs.get("largest_patch_size")
if largest_patch_size is not None:
largest_patch_size = phare_utilities.np_array_ify(largest_patch_size, ndim)
if largest_patch_size.size != ndim:
raise ValueError(
f"Error: largest_patch_size({largest_patch_size.size}) must be size {ndim}"
)
if (largest_patch_size > cells).any():
raise ValueError(
"Error - largest_patch_size should be less than nbr of cells in all directions"
)
if (largest_patch_size <= 0).any():
raise ValueError("Error - largest_patch_size cannot be <= 0")
if (largest_patch_size < smallest_patch_size).any():
raise ValueError(
"Error - largest_patch_size and smallest_patch_size are incompatible"
)
return largest_patch_size, smallest_patch_size
# ------------------------------------------------------------------------------
def check_directory(directory, key):
directory = directory.rstrip(os.path.sep) # trim trailing slashes
if os.path.exists(directory):
if os.path.isfile(directory):
raise ValueError(f"Error: Simulation {key} dir exists as a file.")
if not os.access(directory, os.R_OK | os.W_OK | os.X_OK):
raise ValueError(
f"Directory ({directory}) for {key} does not have the correct permissions"
)
try:
os.makedirs(directory, exist_ok=True)
if not os.path.exists(directory):
raise ValueError(f"1. Creation of the directory {directory} failed")
except FileExistsError as e:
raise ValueError(f"Creation of the directory {directory} failed") from e
return directory
# diag_options = {"format":"phareh5", "options": {"dir": "phare_ouputs/"}}
def check_diag_options(**kwargs):
diag_options = kwargs.get("diag_options")
formats = ["phareh5", "pharevtkhdf"]
if diag_options is not None and "format" in diag_options:
if diag_options["format"] not in formats:
raise ValueError("Error - diag_options format is invalid")
if "options" in diag_options and "dir" in diag_options["options"]:
diag_options["options"]["dir"] = check_directory(
diag_options["options"]["dir"], "diagnostics"
)
valid_modes = ["overwrite"]
if "options" in diag_options and "mode" in diag_options["options"]:
mode = diag_options["options"]["mode"]
if mode not in valid_modes:
raise ValueError(
f"Invalid diagnostics mode {mode}, valid modes are {valid_modes}"
)
if (
"options" in diag_options
and "allow_emergency_dumps" in diag_options["options"]
):
allow_emergency_dumps = diag_options["options"]["allow_emergency_dumps"]
if not isinstance(allow_emergency_dumps, bool):
raise ValueError(
"Invalid allow_emergency_dumps option, should be a boolean"
)
return diag_options
def check_restart_options(**kwargs):
from pyphare.pharein import restarts
valid_keys = [
"dir",
"elapsed_timestamps",
"timestamps",
"mode",
"restart_time", # number or "auto"
"keep_last", # delete obsolete
]
restart_options = kwargs.get("restart_options")
if restart_options:
for key in restart_options:
if key not in valid_keys:
raise ValueError(
f"invalid option ({key}), valid options are {valid_keys}"
)
valid_modes = ["conserve", "overwrite"]
if "mode" not in restart_options:
raise ValueError(f"Restart mode not set, valid modes are {valid_modes}")
if "dir" in restart_options:
restart_options["dir"] = check_directory(restart_options["dir"], "restarts")
mode = restart_options["mode"]
if mode not in valid_modes:
raise ValueError(
f"Invalid restart mode {mode}, valid modes are {valid_modes}"
)
restart_time = restarts.restart_time(restart_options)
if restart_time is not None:
restart_options["restart_time"] = restart_time
elif "restart_time" in restart_options:
restart_options.pop("restart_time") # auto with no existing file to use
return restart_options
def validate_restart_options(sim):
from pyphare.pharein import restarts
if sim.restart_options is not None:
restarts.validate(sim)
def check_refinement(**kwargs):
return kwargs.get("refinement", "boxes")
def check_nesting_buffer(ndim, **kwargs):
refinement_boxes = kwargs.get("refinement_boxes")
has_refinement_boxes = refinement_boxes is not None and len(refinement_boxes) > 0
if check_refinement(**kwargs) == "boxes":
# check_refinement_boxes() normalizes to (None, 1) whenever
# refinement_boxes is empty, ignoring any max_nbr_levels the user
# passed in that case, so has_amr must follow the same rule here.
has_amr = has_refinement_boxes
else:
has_amr = kwargs.get("max_nbr_levels", 1) > 1
if not has_amr:
if "nesting_buffer" in kwargs:
print(
f"WARNING, nesting_buffer({kwargs['nesting_buffer']}) has no effect"
+ " on a simulation with no refinement levels, ignoring"
)
return None
# SAMRAI itself defaults proper_nesting_buffer to 1 and warns when it is 0
# (subprojects/samrai/source/SAMRAI/hier/PatchHierarchy.cpp)
nesting_buffer = phare_utilities.np_array_ify(kwargs.get("nesting_buffer", 1), ndim)
if nesting_buffer.size != ndim:
raise ValueError(f"Error: nesting_buffer must be size {ndim}")
if (nesting_buffer < 1).any():
raise ValueError(
f"Error: nesting_buffer({nesting_buffer}) must be at least 1"
+ " on a simulation with refinement levels"
)
smallest_patch_size = kwargs["smallest_patch_size"]
if (nesting_buffer > smallest_patch_size / 2).any():
raise ValueError(
f"Error: nesting_buffer({nesting_buffer})"
+ f"cannot be larger than half the smallest_patch_size ({smallest_patch_size})"
)
cells = np.asarray(kwargs["cells"])
if (nesting_buffer > cells).any():
raise ValueError(
f"Error: nesting_buffer({nesting_buffer}) incompatible with number of domain cells ({cells})"
)
return nesting_buffer
def check_optional_keywords(**kwargs):
extra = []
if check_refinement(**kwargs) != "boxes":
extra += ["max_nbr_levels"]
return extra
def check_resistivity(**kwargs):
resistivity = kwargs.get("resistivity", 0.0)
if resistivity < 0.0:
raise ValueError("Error: resistivity should not be negative")
return resistivity
def check_hyper_resistivity(**kwargs):
hyper_resistivity = kwargs.get("hyper_resistivity", 0.0001)
if hyper_resistivity < 0.0:
raise ValueError("Error: hyper_resistivity should not be negative")
hyper_mode = kwargs.get("hyper_mode", "constant")
if hyper_mode not in ["constant", "spatial"]:
raise ValueError("Error: hyper_mode should be 'constant' or 'spatial'")
return hyper_resistivity, hyper_mode
def check_clustering(**kwargs):
valid_keys = ["berger", "tile"]
clustering = kwargs.get("clustering", "tile")
if clustering not in valid_keys:
raise ValueError(
f"Error: clustering type is not supported, supported types are {valid_keys}"
)
return clustering
def check_max_mhd_level(**kwargs):
# a pure MHD run needs every level to be MHD
model_options = phare_utilities.listify(kwargs.get("model_options", "HybridModel"))
default = kwargs["max_nbr_levels"] if model_options == ["MHDModel"] else 0
max_mhd_level = kwargs.get("max_mhd_level", default)
if max_mhd_level > kwargs["max_nbr_levels"]:
raise ValueError(
f"Error: max_mhd_level({max_mhd_level}) should be less or equal to max_nbr_levels({kwargs['max_nbr_levels']})"
)
return max_mhd_level
def check_model_options(**kwargs):
model_options = phare_utilities.listify(kwargs.get("model_options", "HybridModel"))
valid_options = {"MHDModel", "HybridModel"}
if not set(model_options).issubset(valid_options):
raise ValueError(
f"Invalid model options: {model_options}. Allowed values are {valid_options}."
)
if "HybridModel" in model_options and not hybrid_is_active(kwargs["interp_order"]):
raise ValueError("Error: HybridModel requires an interp_order")
if "MHDModel" in model_options and not kwargs["mhd_timestepper"]:
raise ValueError("Error: MHDModel requires a non-empty mhd_timestepper")
return model_options
def check_mhd_constants(**kwargs):
gamma = kwargs.get("gamma", 5.0 / 3.0)
eta = kwargs.get("eta", 0.0)
nu = kwargs.get("nu", 0.0)
if not isinstance(gamma, (int, float)) or gamma <= 1:
raise ValueError(f"'gamma' must be a scalar greater than 1, got {gamma!r}")
return float(gamma), eta, nu
def check_mhd_terms(**kwargs):
hall = kwargs.get("hall", False)
return hall
def check_mhd_parameters(**kwargs):
reconstruction = kwargs.get("reconstruction", "")
limiter = kwargs.get("limiter", "")
riemann = kwargs.get("riemann", "")
mhd_timestepper = kwargs.get("mhd_timestepper", "")
return reconstruction, limiter, riemann, mhd_timestepper
def check_refinement_operator(**kwargs):
"""Selects the field-refinement (prolongation) operator order.
order 2 (Linear, the default) is currently the only supported order.
"""
order = kwargs.get("refinement_order", 2)
if order != 2:
raise ValueError(f"Error: refinement_order must be 2 (Linear), got {order}")
return order
# ------------------------------------------------------------------------------
def checker(func):
def wrapper(simulation_object, **kwargs_in):
accepted_keywords = [
"domain_size",
"cells",
"dl",
"particle_pusher",
"final_time",
"time_step",
"time_step_nbr",
"layout",
"interp_order",
"domain_boundaries",
"refined_particle_nbr",
"path",
"nesting_buffer",
"refinement_boxes",
"refinement",
"tagging_threshold",
"clustering",
"smallest_patch_size",
"largest_patch_size",
"diag_options",
"resistivity",
"hyper_resistivity",
"hyper_mode",
"strict",
"restart_options",
"tag_buffer",
"description",
"dry_run",
"write_reports",
"max_mhd_level",
"model_options",
"gamma",
"eta",
"nu",
"hall",
"reconstruction",
"limiter",
"riemann",
"mhd_timestepper",
"refinement_order",
]
kwargs = deepcopy(kwargs_in) # local copy - dictionaries are weird
accepted_keywords += check_optional_keywords(**kwargs)
wrong_kwds = phare_utilities.not_in_keywords_list(accepted_keywords, **kwargs)
if len(wrong_kwds) > 0:
raise ValueError("Error: invalid arguments - " + " ".join(wrong_kwds))
dl, cells = check_domain(**kwargs)
kwargs["strict"] = kwargs.get("strict", False)
kwargs["dl"] = dl
kwargs["cells"] = cells
kwargs["refinement_ratio"] = 2
kwargs["description"] = kwargs.get("description", None)
kwargs["clustering"] = check_clustering(**kwargs)
kwargs["restart_options"] = check_restart_options(**kwargs)
time_stepper = timestepper.resolve_time_stepper(**kwargs)
kwargs.pop("time_step", None)
kwargs.pop("time_step_nbr", None)
kwargs.pop("final_time", None)
kwargs["time_stepper"] = time_stepper
kwargs["interp_order"] = check_interp_order(**kwargs)
kwargs["refinement_ratio"] = 2
kwargs["particle_pusher"] = check_pusher(**kwargs)
kwargs["layout"] = check_layout(**kwargs)
kwargs["path"] = check_path(**kwargs)
ndim = compute_dimension(cells)
kwargs["diag_options"] = check_diag_options(**kwargs)
kwargs["periodicities"], kwargs["domain_boundaries"] = boundary.resolve_boundaries(
ndim, **kwargs
)
kwargs["refined_particle_nbr"] = check_refined_particle_nbr(ndim, **kwargs)
largest, smallest = check_patch_size(ndim, **kwargs)
kwargs["smallest_patch_size"] = smallest
kwargs["largest_patch_size"] = largest
kwargs["nesting_buffer"] = check_nesting_buffer(ndim, **kwargs)
kwargs["tag_buffer"] = kwargs.get("tag_buffer", 1)
kwargs["refinement"] = check_refinement(**kwargs)
if kwargs["refinement"] == "boxes":
(
kwargs["refinement_boxes"],
kwargs["max_nbr_levels"],
) = check_refinement_boxes(ndim, **kwargs)
else:
if "max_nbr_levels" not in kwargs:
print("WARNING, 'max_nbr_levels' is not set, defaulting to 1")
kwargs["max_nbr_levels"] = kwargs.get("max_nbr_levels", 1)
kwargs["refinement_boxes"] = None
kwargs["tagging_threshold"] = kwargs.get("tagging_threshold", 0.1)
kwargs["resistivity"] = check_resistivity(**kwargs)
nu, hyper_mode = check_hyper_resistivity(**kwargs)
kwargs["hyper_resistivity"] = nu
kwargs["hyper_mode"] = hyper_mode
kwargs["dry_run"] = kwargs.get(
"dry_run", os.environ.get("PHARE_DRY_RUN", "0") == "1"
)
# is per rank, not per node (yet)
kwargs["write_reports"] = kwargs.get("write_reports", False)
kwargs["max_mhd_level"] = check_max_mhd_level(**kwargs)
gamma, eta, nu = check_mhd_constants(**kwargs)
kwargs["gamma"] = gamma
kwargs["eta"] = eta
kwargs["nu"] = nu
hall = check_mhd_terms(**kwargs)
kwargs["hall"] = hall
reconstruction, limiter, riemann, mhd_timestepper = check_mhd_parameters(
**kwargs
)
kwargs["reconstruction"] = reconstruction
kwargs["limiter"] = limiter
kwargs["riemann"] = riemann
kwargs["mhd_timestepper"] = mhd_timestepper
kwargs["model_options"] = check_model_options(**kwargs)
kwargs["refinement_order"] = check_refinement_operator(**kwargs)
return func(simulation_object, **kwargs)
return wrapper
# ------------------------------------------------------------------------------
[docs]
class Simulation:
"""
**Usage example:**
This declares a 2D simulation of 100x100 cells
with an isotropic mesh size of 0.2. The simulation will run
1000 time steps of dt=0.001 and so will stop at t=1
The simulation will run with adaptive mesh refinement and evolve up to 3 levels,
i.e. a base coarsest mesh with up to 2 additional refinement levels.
Diagnostics, if declared, will be saved as native PHARE HDF5 (default format)
in the directory `diag_outputs` and will overwrite any existing h5 files there.
The resistivity and hyper-resistivity are set to constant custom values.
.. code-block:: python
import pyphare.pharein as ph
ph.Simulation(
# time evolution parameters
time_step_nbr=1000,
time_step=0.001,
# Domain parameters
cells=(100,100),
dl=(0.2, 0.2),
# AMR parameters
refinement="tagging",
max_nbr_levels=3,
# general physics parameters
hyper_resistivity=0.001,
resistivity=0.001,
# diagnostics and restart parameters
diag_options={"format": "phareh5",
"options": {"dir": diag_outputs,
"mode":"overwrite"}},
)
**Time parameters:**
* **final_time** (``float``), final simulation time. Use with time_step OR time_step_nbr
* **time_step** (``float``), simulation time step. Use with time_step_nbr OR final_time
* **time_step_nbr** (``int``), number of time step to perform. Use with final_time OR time_step
``time_step`` may also be given as a dict selecting the time-stepping mode:
* ``{"mode": "constant", "value": <dt>}`` - equivalent to passing ``time_step=<dt>``
(``"value"`` is optional and may be replaced by ``final_time``/``time_step_nbr``).
* ``{"mode": "adaptive", "cfl_wave": <w>, "cfl_diffusive": <d>}`` - the time step is
recomputed each step from a CFL constraint. Requires ``final_time`` and
is incompatible with ``time_step_nbr``.
* **cfl_wave** (``float``), hyperbolic/wave CFL coefficient. Normalized so 1 is
the stability limit; choose in (0, 1]. In hall mhd and hybrid,
whistler wave speed limits is used.
* **cfl_diffusive** (``float``), diffusive CFL coefficient. Normalized so 1 is
the diffusion stability limit; choose in (0, 1]. Defaults to ``cfl_wave``. Only
relevant when resistivity is non-zero.
With adaptive stepping there is no fixed dump grid, so diagnostics require explicit
``write_timestamps``.
.. code-block:: python
ph.Simulation(
time_step_nbr=1000,
time_step=0.001,
# ....
)
is equivalent to:
.. code-block:: python
ph.Simulation(
time_step_nbr=1000,
final_time=1.,
# ....
)
or even to:
.. code-block:: python
ph.Simulation(
time_step=0.001,
final_time=1.,
# ....
)
**Domain/grid parameters:**
The number of dimensions of the simulation is deduced from the length
of these parameters.
* **dl** (``float``, ``tuple``) grid spacing dx, (dx,dy) or (dx,dy,dz) in 1D, 2D or 3D.
A single float value in 2D or 3D are assumed equal for each dimension.
Use this parameter with either `domain_size` OR `cells`
* **domain_size** (``float`` or ``tuple``)
size of the physical domain Lx, (Lx,Ly), (Lx,Ly,Lz) in 1D, 2D or 3D
Single float is assumed equal for each direction. Use this parameter with either `cells` or `dl`
* **cells** (``int`` or ``tuple``)
number of cells nx or (nx, ny) or (nx, ny, nz) in 1, 2 and 3D.
Single int is assumed equal for each direction
Use this parameter with either `domain_size` or `dl`
**Expert parameters:**
These parameters are more advanced, modify them at your own risk
* **layout** (``str``), layout of the physical quantities on the mesh (default = "yee")
For instance:
.. code-block:: python
ph.Simulation(
dl=(0.1, 0.1),
domain_size=(100,100),
# ....
)
is equivalent to:
.. code-block:: python
ph.Simulation(
cells=(1000, 1000),
domain_size=(100,100),
# ....
)
or even to:
.. code-block:: python
ph.Simulation(
cells=(1000, 1000),
dl=(0.1,0.1),
# ....
)
**Diagnostics output parameters:**
* **diag_options** (``dict``)
* **format** (``str``), {"phareh5" (default), "pharevtkhdf"}, on-disk format of the diagnostics files. See :doc:`../usage/diagnostics` for what each format means.
* **options** (``dict``)
* **dir** (``str``) directory where diagnostics files are written (default : './')
* **mode** (``str``), {"overwrite"}, if set to "overwrite", any existing diagnostics file in `dir`
is truncated (wiped) at the start of the run. If omitted (the default), an existing file is
opened and kept as-is instead, so new data is added onto it - useful when restarting a
simulation, so diagnostics keep accumulating in the same file rather than being lost.
* **fine_dump_lvl_max** (``int``), default=None. This does not affect the regular diagnostics
dumps, which always cover the whole hierarchy at the times given by each diagnostic's
`write_timestamps`. If set, it additionally triggers an extra dump on every substep (much
more frequent than the regular schedule on refined levels), limited to levels up to and
including `fine_dump_lvl_max`. If left unset (the default), no such extra dump happens at
all - only the regular, whole-hierarchy dumps occur.
* **allow_emergency_dumps** (``bool``), default=False, if True, allows PHARE to write an out-of-schedule diagnostics dump when the run is interrupted abnormally.
Note: `diag_options["format"]` (the diagnostics file format) is unrelated to
the separate, unused-today `diag_export_format` keyword below - the latter is
reserved for a currently single-valued option ("hdf5") and should not be confused
with the former.
* **diag_export_format** (``str``), currently always "hdf5" (no other value is accepted).
**Adaptive Mesh Refinement (AMR) parameters:**
* **refinement** (``str``), {"boxes" (default), "tagging"}, how refined regions are chosen.
* "tagging" - refined regions are recomputed at run time from the solution itself: cells where a gradient-based criterion exceeds `tagging_threshold` are tagged, then clustered into patches (buffered by `tag_buffer`). Refined regions therefore move and grow/shrink as the physics evolves. This is the mode used for actual science production runs.
* "boxes" - refined regions are the fixed, user-given `refinement_boxes`, identical at every time step. Mostly used in tests, where fully deterministic, reproducible refined regions matter more than adapting to the physics.
* **tagging_threshold** (``float``), default=0.1, used only when `refinement="tagging"`. Threshold of the tagging criterion above which a cell is flagged for refinement. Lower values tag more cells and produce more/larger refined regions. See :ref:`tagging-for-refinement` for the underlying theory.
* **max_nbr_levels** (``int``), default=1, max number of levels in the hierarchy. With `refinement="boxes"` this is derived automatically from the number of levels given in `refinement_boxes`; with `refinement="tagging"` it must be given explicitly (it otherwise silently defaults to 1, i.e. no refinement).
* **tag_buffer** (``int``), default=1, number of cells by which each tagged cell is grown, in every direction, before clustering into boxes. E.g. with `tag_buffer=1`, a single tagged cell becomes surrounded by a 1-cell-wide layer of also-tagged cells: 3 tagged cells in 1D, 9 in 2D. The larger `tag_buffer`, the wider refined regions will be around tagged cells.
* **clustering** (``str``), {"berger", "tile" (default)}, type of :ref:`clustering` to use for AMR. :ref:`tile <tiling>` results in wider patches, less artifacts and better scalability than :ref:`berger <berger-rigoutsos>`.
**Expert parameters:**
These parameters are more advanced, modify them at your own risk
* **nesting_buffer** (``ìnt``), default=1 minimum gap in coarse cells from the border of a level and any refined patch border. Has no effect (and is not sent to SAMRAI) if the simulation has no refinement levels.
* **refinement_boxes** (``dict``), default=None, used only when `refinement="boxes"`. Explicitly gives the
fixed refined regions to create, level by level.
* Each key ``"Li"`` (``"L0"``, ``"L1"``, ...) identifies a level. Its value describes the box(es), given
in level ``Li``'s own cell-index coordinates, that will be refined into level ``Li+1``. So boxes under
``"L0"`` define where level 1 patches will be, boxes under ``"L1"`` define where level 2 patches will
be, and so on.
* For a given level, boxes are given as a dict mapping an arbitrary box name (``"B0"``, ``"B1"``, ...,
only used to identify boxes in error messages) to a pair of index tuples ``(lower, upper)``: the
lower and upper cell indices of that box, inclusive, in x, (x, y) or (x, y, z) depending on the
simulation's dimension.
.. code-block:: python
refinement_boxes={
"L0": {"B0": [(10,), (19,)]}, # 1D: on L0, cells 10 to 19 become refined into L1
"L1": {"B0": [(30,), (49,)]}, # on L1, cells 30 to 49 (L1's own indexing) become L2
}
would produce a hierarchy with 3 levels (L0, L1, L2), the number of levels being deduced from the number
of keys given here (`max_nbr_levels` does not need to be set in that case).
.. warning::
These boxes are fixed for the entire simulation: they never move, grow or shrink, regardless of how
the physics evolves. Level boundaries therefore stay at the same location for the whole run, which
lets high-frequency noise generated at those boundaries accumulate there over time instead of being
swept away as a tagging-based refined region would do. For this reason `refinement_boxes` is mostly
useful for tests, where deterministic, reproducible refined regions matter more than accuracy - see
`refinement="tagging"` above for the mode intended for science production runs.
* **smallest_patch_size** (``int`` or ``tuple``), minimum number of cells in a patch in each direction
This parameter cannot be smaller than the number of field ghost nodes
* **largest_patch_size** (``int`` or ``tuple``), maximum size of a patch in each direction
**Restart parameters:**
These parameters control both how checkpoints are dumped during a simulation and how a simulation
restarts from a previous checkpoint.
* **restart_options** (``dict``), default=None (no restart files are read or written at all)
* **dir** (``str``), default="./", path for restart files
* **mode** (``str``), default="conserve", mode of the restart files
* "conserve" - (default), will conserve existing files
* "overwrite" - will overwrite existing files
* **restart_time** (``float`` or ``"auto"``), default=None (fresh start, not a restart), time at which to restart the simulation. If "auto", the latest available restart file in `dir` is used.
* **timestamps** (``list``), default=None, list of simulation times at which to dump a restart file. Must be in ascending order and consistent with `time_step`. If neither this nor `elapsed_timestamps` is set, no restart file is ever dumped.
* **elapsed_timestamps** (``list`` of ``float`` seconds or ``datetime.timedelta``), default=None, dump a restart file every time this much wall-clock time has elapsed since the simulation started, instead of at fixed simulation times. Can be combined with `timestamps`.
* **keep_last** (``int``), default=None (keep every restart directory ever written, nothing is deleted). If set, only the `keep_last` most recent restart directories are kept - older ones are deleted automatically as new ones are written. It is a count rather than a bool because it expresses *how many* to retain, not just whether to prune at all.
**Hybrid parameters:**
These parameters only apply to a Hybrid simulation, i.e. one declared with
``model_options=["HybridModel"]`` (the default, paired with a
:class:`~pyphare.pharein.MaxwellianFluidModel` block instead of an
:class:`~pyphare.pharein.MHDModel` one). They are ignored on pure-MHD runs.
* **interp_order** (``int``), 1, 2 or 3 (default=1 if "HybridModel" is among
``model_options``) particle b-spline order; omit it for a run with no hybrid
model, where it has no meaning
* **particle_pusher** (``str``), algo to push particles (default = "modifiedBoris")
* **resistivity** (``float``), default=0.0, Hybrid Ohm's law resistivity value
* **hyper_resistivity** (``float``), default=0.0001, Hybrid Ohm's law hyper-resistivity value
* **hyper_mode** (``str``), {"constant" (default), "spatial"}, "constant" uses `hyper_resistivity`
as is; "spatial" scales it locally by ``(|B|/(n + 0.1) + 1) / 4**level``
**Expert parameters:**
These parameters are more advanced, modify them at your own risk
* **refined_particle_nbr** (``ìnt``), number of refined particles per coarse particle. This is not a
free parameter: only a handful of values are valid, and which ones depends on `ndim` and
`interp_order`. The authoritative list of valid combinations is `possibleSimulators()` in
`src/core/utilities/meta/meta_utilities.hpp`, since each combination corresponds to a distinct
pre-compiled instantiation of the code - passing a value outside that list raises an error at
`Simulation` construction time (mirrored on the Python side in `valid_refined_particle_nbr`,
`pyphare/pharein/simulation.py`). If omitted, the first valid value for the given
`ndim`/`interp_order` is used as the default.
**MHD parameters:**
These parameters only apply to an MHD simulation, i.e. one declared with
``model_options=["MHDModel"]`` (paired with an :class:`~pyphare.pharein.MHDModel`
block instead of a :class:`~pyphare.pharein.MaxwellianFluidModel` one). PHARE
currently runs either a Hybrid (kinetic ions / fluid electrons) or an MHD
simulation, never a mix of both in the same hierarchy.
* **model_options** (``str`` or ``list``), {"HybridModel" (default), "MHDModel"}, which physics this simulation evolves.
* **max_mhd_level** (``int``), default=0, number of AMR levels evolved with MHD. Must be <= `max_nbr_levels`; for an MHD simulation it is typically set equal to `max_nbr_levels` (every level is MHD).
* **gamma** (``float``), default=5/3, adiabatic index (heat capacity ratio) of the MHD fluid.
* **eta** (``float``), default=0.0, MHD resistivity.
* **nu** (``float``), default=0.0, MHD hyper-resistivity.
* **hall** (``bool``), default=False, whether the Hall term is included in the MHD Ohm's law.
* **reconstruction** (``str``), spatial reconstruction scheme used by the MHD finite-volume solver (e.g. "WENOZ").
* **limiter** (``str``), slope limiter used with the reconstruction scheme (e.g. "None").
* **riemann** (``str``), Riemann solver used at cell interfaces (e.g. "Rusanov").
* **mhd_timestepper** (``str``), mandatory for an MHD simulation, time integration scheme for the MHD solver (e.g. "TVDRK3").
`reconstruction`, `limiter`, `riemann` and `hall` select which pre-compiled MHD module is
loaded, so their combination must be one that was built (see ``res/sim/all.txt``).
Misc:
* **description** (``string``), [default=None] arbitrary string for per simulation context - injected in output files when feasible
* **strict** (``bool``), turns warnings into errors (default False)
* **dry_run** (``bool``), default=False (or the `PHARE_DRY_RUN` environment variable if set), builds and validates the simulation - constructing models, populating the dict, building the hierarchy - without actually initializing or advancing it. `Simulator.initialize()`, `advance()` and `run()` become no-ops. Useful to check that a script is well-formed without paying for a real run.
* **domain_boundaries** (``dict``) domain boundaries per location (e.g. "xlower"); a direction is periodic unless both of its locations are given (MHD only)
"""
@checker
def __init__(self, **kwargs):
if global_vars.sim is not None:
raise RuntimeError("simulation is already created")
global_vars.sim = self
for k, v in kwargs.items():
object.__setattr__(self, k, v)
self.ndim = compute_dimension(self.cells)
self.diagnostics = {}
self.model = None
self.electrons = None
self.load_balancer = None
validate_restart_options(self)
def simulation_domain(self):
return [dl * n for dl, n in zip(self.dl, self.cells)]
def within_simulation_duration(self, time_period):
return self.time_stepper.within_simulation_duration(time_period)
def within_simulation_extent(self, extent):
domain = self.simulation_domain()
if len(extent) == 2:
# 1D case
return extent[0] >= domain[0] and extent[1] <= domain[1]
raise NotImplementedError("Error: 2D and 3D not implemented yet")
def restart_file_path(self):
assert self.restart_options is not None
return self.restart_options.get("dir", "phare_outputs")
def start_time(self):
return self.time_stepper.start_time
def is_from_restart(self):
if self.restart_options is not None and "restart_time" in self.restart_options:
return self.restart_options["restart_time"] is not None
return False
def __getattr__(
self, name
): # stops pylint complaining about dynamic class attributes not existing
...
# dill serialization uses __getattr__
# but without these it causes errors
def __getstate__(self):
return vars(self)
def __setstate__(self, state):
vars(self).update(state)
# ------------------------------------------------------------------------------
def add_diagnostics(self, diag):
"""
:meta private:
"""
if diag.name in self.diagnostics:
raise ValueError(f"Error: diagnostics {diag.name} already registered")
# check whether the spatial extent of the diagnostics is valid, given the domain size
if diag.extent() is not None and not self.within_simulation_extent(
diag.extent()
):
raise RuntimeError("Error: invalid diagnostics spatial extent")
self.diagnostics[diag.name] = diag
# ------------------------------------------------------------------------------
def is_restartable_compared_to(self, sim):
"""
:meta private:
"""
# to be considered https://github.com/PHAREHUB/PHARE/issues/666
from pyphare.pharein import restarts
return restarts.is_restartable_compared_to(self, sim)
# ------------------------------------------------------------------------------
def count_diagnostics(self, type_name):
"""
:meta private:
"""
return len(
[
diag
for diagname, diag in self.diagnostics.items()
if diag.type == type_name
]
)
# ------------------------------------------------------------------------------
def set_model(self, model):
"""
:meta private:
"""
self.model = model
def set_electrons(self, electrons):
"""
:meta private:
"""
self.electrons = electrons
# ------------------------------------------------------------------------------
def serialize(sim):
"""
:meta private:
"""
# pickle cannot handle simulation objects
import codecs
import dill
return codecs.encode(dill.dumps(de_numpify_simulation(deepcopy(sim))), "hex")
def deserialize(hex):
""":meta private:"""
import codecs
import dill
return re_numpify_simulation(dill.loads(codecs.decode(hex, "hex")))