nmag-python-3 0.0.2__py3-none-any.whl

simulation/hysteresis_schedule.py

@@ -0,0 +1,180 @@
+"""Schedule parsing and counter arithmetic for hysteresis runs."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any, cast
+
+from when import When
+
+from .clock import SimulationClock
+
+Action = Callable[[Any], Any]
+ScheduleInput = list[tuple[object, ...]]
+ScheduledAction = tuple[Action, When]
+CounterTriple = tuple[Any | None, Any | None, Any | None]
+
+_subsequent_spaces = re.compile(r"[ \t_]+")
+
+
+def _string_normalise(s: str, lower: bool = True, spaces: str | None = "_") -> str:
+    """
+    Used by `_append_x_list` to obtain a standard string format.
+    Examples:
+        'save  fields' --> 'save_fields'
+        'Save_Fields'  --> 'save_fields'
+    """
+    ns = s
+    if lower:
+        ns = s.lower()
+    if spaces is not None:
+        ns = re.sub(_subsequent_spaces, spaces, ns)
+    return ns
+
+
+def _append_x_list(
+    target_list: list[ScheduledAction],
+    input_list: ScheduleInput,
+    prefix: str = "",
+    predefined_actions: dict[str, Action] | None = None,
+) -> None:
+    """
+    Internally used by `_join_save_and_do_lists` to parse the
+    multi-argument 'save' and 'do' tuples.
+    """
+    if predefined_actions is None:
+        predefined_actions = {}
+
+    try:
+        for tuple_item in input_list:
+            list_item = list(tuple_item)
+            if not list_item:
+                continue
+
+            things = list_item[0:-1]
+            when = list_item[-1]
+
+            for thing in things:
+                if callable(thing):
+                    target_list.append((cast(Action, thing), cast(When, when)))
+                    continue
+
+                if isinstance(thing, str):
+                    normalised_thing = _string_normalise(f"{prefix} {thing}")
+                    if normalised_thing in predefined_actions:
+                        action = predefined_actions[normalised_thing]
+                        target_list.append((action, cast(When, when)))
+                        continue
+                    else:
+                        # Try without prefix
+                        normalised_thing = _string_normalise(thing)
+                        if normalised_thing in predefined_actions:
+                            action = predefined_actions[normalised_thing]
+                            target_list.append((action, cast(When, when)))
+                            continue
+
+                # If we are here, the 'thing' is not a callable and not
+                # a recognized string.
+                msg = (
+                    f"Error in optional argument '{prefix}' of method "
+                    f"'hysteresis': you want to {prefix} '{thing}' "
+                    f"but I don't know how to do it. Hint: when specifying "
+                    f"what to {prefix} you can use a string or a function. "
+                    f"Available strings are: {', '.join(predefined_actions.keys())}."
+                )
+                raise ValueError(msg)
+
+    except TypeError as e:
+        msg = (
+            f"Bad syntax for argument '{prefix}' of the method 'hysteresis': "
+            f"remember that you should provide a list of tuples "
+            f"(things_to_{prefix}, when). You can also provide tuples "
+            f"with many things to save, such as (thing1, thing2, "
+            f"..., when)."
+        )
+        raise ValueError(msg) from e
+
+
+def _join_save_and_do_lists(
+    save_list: ScheduleInput,
+    do_list: ScheduleInput,
+    predefined_actions: dict[str, Action] | None = None,
+) -> list[ScheduledAction]:
+    """
+    Takes 'save' and 'do' parameters from the 'hysteresis' method
+    and joins them into a unique list.
+    Tags (e.g., "save averages") are replaced with the appropriate functions.
+    Also checks that the provided tags actually exist.
+    """
+    if predefined_actions is None:
+        predefined_actions = {}
+
+    joint_list: list[ScheduledAction] = []
+
+    # Note: It is important to process 'do' before 'save'.
+    # A 'do' command might be 'next_stage', and 'save' commands
+    # need to know if this is the last step of the stage.
+    _append_x_list(joint_list, do_list, prefix="do", predefined_actions=predefined_actions)
+    _append_x_list(joint_list, save_list, prefix="save", predefined_actions=predefined_actions)
+
+    # XXX Matteo, can we at this point order the save_ entries such that
+    # the save_restart is the last? See my explanation in ticket:169.
+    # Hans, 11/ll/2008
+
+    return joint_list
+
+
+def _next_deltas(
+    event: When,
+    clock: SimulationClock,
+    suggest: CounterTriple | None = None,
+    tols: dict[str, Any] | None = None,
+) -> CounterTriple:
+    """
+    Return the next occurrence of the given event as a triple of deltas:
+    - (delta_step, delta_time, delta_real_time)
+    """
+
+    def delta(name: str) -> Any | None:
+        n = event.next_time(name, clock, tols=tols)
+        return n - clock[name] if not isinstance(n, bool) else None
+
+    def minimum(ls: list[Any | None]) -> Any | None:
+        return min((item for item in ls if item is not None), default=None)
+
+    delta_step, delta_time, delta_real_time = suggest or (None, None, None)
+
+    delta_step = minimum([delta("step"), delta("stage_step"), delta_step])
+    delta_time = minimum([delta("time"), delta("stage_time"), delta_time])
+    delta_real_time = minimum([delta("real_time"), delta_real_time])
+
+    return (delta_step, delta_time, delta_real_time)
+
+
+def _next_time(
+    event: When,
+    clock: SimulationClock,
+    tols: dict[str, Any] | None = None,
+) -> CounterTriple:
+    """
+    Returns a triple of absolute counter values for the next event:
+    - (next_step, next_time, next_real_time)
+    """
+
+    def delta(name: str, starting_time: str | None = None) -> Any | None:
+        n = event.next_time(name, clock, tols=tols)
+        if isinstance(n, bool):
+            return None
+        return n - clock[starting_time] if starting_time else n
+
+    def minimum(ls: list[Any | None]) -> Any | None:
+        return min((item for item in ls if item is not None), default=None)
+
+    next_time = minimum([delta("time", "zero_stage_time"), delta("stage_time")])
+
+    next_step = minimum([delta("step", "zero_stage_step"), delta("stage_step")])
+
+    next_real_time = delta("real_time")
+
+    return (next_step, next_time, next_real_time)

simulation/inference/__init__.py

@@ -0,0 +1,3 @@
+from .inference import InferenceEngine, InferenceEntity
+
+__all__ = ["InferenceEngine", "InferenceEntity"]

simulation/inference/inference.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+log = logging.getLogger("nmagmake")
+
+
+@dataclass
+class InferenceEntity:
+    name: str
+    depends_on: list[str] = field(default_factory=lambda: [])
+    how_to_make: list[Callable[..., Any]] = field(default_factory=lambda: [])
+    also_updates: list[str] = field(default_factory=lambda: [])
+    _is_prerequisite: list[str] = field(default_factory=lambda: [], init=False)
+    _is_uptodate: bool = field(default=False, init=False)
+
+
+class InferenceEngine:
+    def __init__(self, entities: list[dict[str, Any]] | None = None) -> None:
+        self.entities: dict[str, InferenceEntity] = {}
+        if entities:
+            for e_desc in entities:
+                ie = InferenceEntity(**e_desc)
+                self.entities[ie.name] = ie
+
+        self._build_backlinks()
+        self._check_for_cycles()
+
+    def _build_backlinks(self) -> None:
+        """Connects dependencies to their dependents and validates existence."""
+        for name, ie in self.entities.items():
+            for dep in ie.depends_on:
+                if (ie_dep := self.entities.get(dep)) is None:
+                    raise KeyError(f"Dependency '{dep}' required by '{name}' not found.")
+                ie_dep._is_prerequisite.append(name)
+
+    def _check_for_cycles(self) -> None:
+        """Detects circular dependencies using DFS to prevent infinite recursion."""
+        visited: set[str] = set()
+        rec_stack: set[str] = set()
+
+        def has_cycle(name: str) -> bool:
+            visited.add(name)
+            rec_stack.add(name)
+
+            for neighbor in self.entities[name].depends_on:
+                if neighbor not in visited:
+                    if has_cycle(neighbor):
+                        return True
+                elif neighbor in rec_stack:
+                    return True
+
+            rec_stack.remove(name)
+            return False
+
+        for node in self.entities:
+            if node not in visited:
+                if has_cycle(node):
+                    raise ValueError(f"Circular dependency detected involving '{node}'")
+
+    def invalidate(self, name: str) -> None:
+        """Recursively marks an entity and its dependents as dirty."""
+        if (ie := self.entities.get(name)) is None:
+            raise KeyError(f"Entity '{name}' is unknown.")
+
+        if ie._is_uptodate:
+            ie._is_uptodate = False
+            log.debug(f"Invalidated: {name}")
+            for dependent_name in ie._is_prerequisite:
+                self.invalidate(dependent_name)
+
+    def make(self, name: str, **make_args: Any) -> None:
+        """Builds target and dependencies recursively."""
+        if (ie := self.entities.get(name)) is None:
+            raise KeyError(f"Cannot build unknown entity '{name}'.")
+
+        if ie._is_uptodate:
+            log.debug(f"'{name}' is up-to-date.")
+            return
+
+        for dep_name in ie.depends_on:
+            self.make(dep_name, **make_args)
+
+        log.info(f"Building: {name}")
+        for step in ie.how_to_make:
+            step(**make_args)
+
+        for also_name in ie.also_updates:
+            if other := self.entities.get(also_name):
+                other._is_uptodate = True
+
+        ie._is_uptodate = True

simulation/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 inline type information.

simulation/quantity.py

@@ -0,0 +1,88 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from si.physical import SI
+
+
+@dataclass(frozen=True)
+class Quantity:
+    """A dataclass describing a physical quantity for data saving.
+
+    A quantity is a description of any thing that may be saved inside
+    a ndt file. It may just represent an integer-floating point number
+    or a vector field. The Quantity class is a descriptor for such a thing.
+    It contains details about the corresponding type, SI unit, the id name,
+    the signature (indices and per-material).
+    """
+
+    name: str
+    type: str  # 'int', 'float', 'field', 'pfield', 'date'
+    units: SI | None
+    signature: str | None = None
+    context: str | None = None
+    parent: Optional["Quantity"] = None
+
+    def __post_init__(self) -> None:
+        if self.signature is None:
+            object.__setattr__(self, "signature", self.name)
+
+    def sub_quantity(self, name: str) -> "Quantity":
+        """Creates a new Quantity representing a sub-component."""
+        return self.__class__(
+            name=name,
+            type=self.type,
+            units=self.units,
+            signature=self.signature,
+            context=self.context,
+            parent=self,
+        )
+
+
+UNIT_DIMENSIONLESS = SI(1)
+UNIT_SECONDS = SI("s")
+UNIT_A_PER_M = SI("A/m")
+UNIT_A_PER_M2 = SI("A/m^2")
+UNIT_A_PER_M_PER_S = SI("A/m/s")
+UNIT_INVERSE_SECONDS = SI("1/s")
+UNIT_J_PER_M3 = SI("J/m^3")
+UNIT_AMPERE = SI("A")
+
+
+known_quantities: list[Quantity] = [
+    #         name                 type       unit           signature context
+    Quantity("id", "int", UNIT_DIMENSIONLESS, None),
+    Quantity("step", "int", UNIT_DIMENSIONLESS, None),
+    Quantity("stage_step", "int", UNIT_DIMENSIONLESS, None),
+    Quantity("stage", "int", UNIT_DIMENSIONLESS, None),
+    Quantity("last_step_dt", "float", UNIT_SECONDS, None),
+    Quantity("time", "float", UNIT_SECONDS, None),
+    Quantity("stage_time", "float", UNIT_SECONDS, None),
+    Quantity("real_time", "float", UNIT_SECONDS, None),
+    Quantity("unixtime", "float", UNIT_SECONDS, None),
+    Quantity("maxangle", "float", UNIT_DIMENSIONLESS, None),
+    Quantity("localtime", "date", None, None),
+    Quantity("H_total", "field", UNIT_A_PER_M, "_?_*"),
+    Quantity("M", "field", UNIT_A_PER_M, "_?_*"),
+    Quantity("m", "pfield", UNIT_DIMENSIONLESS, "_?_*"),
+    Quantity("pin", "pfield", UNIT_DIMENSIONLESS, None),
+    Quantity("current_density", "pfield", UNIT_A_PER_M2, "_*", "stt"),
+    Quantity("dmdt", "field", UNIT_A_PER_M_PER_S, "_?_*"),
+    Quantity("dm_dcurrent", "field", UNIT_INVERSE_SECONDS, "_?_*", "stt"),
+    Quantity("H_ext", "field", UNIT_A_PER_M, "_*"),
+    Quantity("H_anis", "field", UNIT_A_PER_M, "_?_*", "anis"),
+    Quantity("H_exch", "field", UNIT_A_PER_M, "_?_*", "exch"),
+    Quantity("H_demag", "field", UNIT_A_PER_M, "_*", "demag"),
+    Quantity("E_total", "field", UNIT_J_PER_M3, "_?"),
+    Quantity("E_ext", "field", UNIT_J_PER_M3, "_?"),
+    Quantity("E_anis", "field", UNIT_J_PER_M3, "_?", "anis"),
+    Quantity("E_exch", "field", UNIT_J_PER_M3, "_?", "exch"),
+    Quantity("E_demag", "field", UNIT_J_PER_M3, "_?", "demag"),
+    Quantity("phi", "field", UNIT_AMPERE, None, "demag"),
+    Quantity("rho", "field", UNIT_A_PER_M2, None, "demag"),
+]
+
+known_quantities_by_name: dict[str, Quantity] = {q.name: q for q in known_quantities}
+
+known_field_quantities: list[Quantity] = [
+    q for q in known_quantities if q.type in ("field", "pfield")
+]