Source code for pyphare.pharein.simulation

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")))