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

simulation/data_writer_collection.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, cast, runtime_checkable
+
+from si.physical import SI
+from simulation.quantity import Quantity
+
+log = logging.getLogger("nmag")
+
+
+@dataclass(frozen=True)
+class _SubfieldRequest:
+    field_name: str
+    prefix: str
+    mat_name: str | None = None
+
+
+class MaterialSource(Protocol):
+    name: str
+
+
+@runtime_checkable
+class SimulationSource(Protocol):
+    name: str
+    last_spatial_save_timings_seconds: dict[str, float]
+    last_maxangle_timings_seconds: dict[str, float]
+
+    @property
+    def id(self) -> int: ...
+
+    @property
+    def step(self) -> int: ...
+
+    @property
+    def stage(self) -> int: ...
+
+    @property
+    def stage_step(self) -> int: ...
+
+    @property
+    def time(self) -> SI: ...
+
+    @property
+    def stage_time(self) -> SI: ...
+
+    @property
+    def real_time(self) -> SI: ...
+
+    @property
+    def last_step_dt(self) -> SI: ...
+
+    def get_subfield_average(self, subfieldname: str, mat_name: str | None = None) -> Any: ...
+
+    def get_maxangle_average(self, field_name: str) -> float | None: ...
+
+    def get_materials_of_field(self, field_name: str) -> list[MaterialSource]: ...
+
+    def get_all_field_names(self) -> list[str]: ...
+
+    def save_spatial_fields(self, filename: str, fieldnames: list[str]) -> None: ...
+
+
+class DataWriterCollectionMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _base_columns(self, source: SimulationSource) -> list[tuple[str, Any]]:
+        lt = time.localtime()
+        lt_str = f"{lt[0]:04d}/{lt[1]:02d}/{lt[2]:02d}-{lt[3]:02d}:{lt[4]:02d}:{lt[5]:02d}"
+
+        return [
+            ("id", source.id),
+            ("step", source.step),
+            ("stage_step", source.stage_step),
+            ("stage", source.stage),
+            ("last_step_dt", source.last_step_dt),
+            ("time", source.time),
+            ("stage_time", source.stage_time),
+            ("real_time", source.real_time),
+            ("unixtime", SI(time.time(), "s")),
+            ("localtime", lt_str),
+        ]
+
+    def _append_average_columns(
+        self,
+        columns: list[tuple[str, Any]],
+        current_quantities: list[Quantity] | None,
+        quantity: Quantity | None,
+        prefix: str,
+        average: Any,
+    ) -> None:
+        if isinstance(average, list):
+            for i, comp_value in enumerate(cast(list[Any], average)):
+                comp_name = f"{prefix}_{i}"
+                columns.append((comp_name, comp_value))
+                if current_quantities is not None and quantity is not None:
+                    current_quantities.append(quantity.sub_quantity(comp_name))
+        else:
+            columns.append((prefix, average))
+            if current_quantities is not None and quantity is not None:
+                current_quantities.append(quantity.sub_quantity(prefix))
+
+    @staticmethod
+    def _source_has_subfield(source: SimulationSource, field_name: str) -> bool:
+        predicate = getattr(source, "is_subfield_available", None)
+        if predicate is None:
+            return True
+        try:
+            return bool(predicate(field_name))
+        except KeyError:
+            log.debug("Skipping unavailable subfield %s", field_name)
+            return False
+
+    def _gather_data(
+        self, source: SimulationSource
+    ) -> tuple[list[tuple[str, Any]], list[Quantity]]:
+        columns = self._base_columns(source)
+        current_quantities: list[Quantity] = [self.quantities_by_name[name] for name, _ in columns]
+        subfield_requests: list[_SubfieldRequest] = []
+        for quantity in self.quantities:
+            self._collect_quantity_subfields(
+                source,
+                quantity,
+                columns,
+                current_quantities,
+                subfield_requests,
+            )
+
+        writes_maxangle = self._collect_initial_maxangle(
+            source,
+            columns,
+            current_quantities,
+        )
+
+        self._subfield_requests = subfield_requests
+        self._writes_maxangle = writes_maxangle
+
+        return columns, current_quantities
+
+    def _collect_quantity_subfields(
+        self,
+        source: SimulationSource,
+        quantity: Quantity,
+        columns: list[tuple[str, Any]],
+        current_quantities: list[Quantity],
+        subfield_requests: list[_SubfieldRequest],
+    ) -> None:
+        field_name = quantity.name
+        if quantity.type not in ["field", "pfield"] or not self._source_has_subfield(
+            source,
+            field_name,
+        ):
+            return
+        if "?" not in (quantity.signature or ""):
+            self._collect_subfield_average(
+                source,
+                field_name,
+                field_name,
+                quantity,
+                columns,
+                current_quantities,
+                subfield_requests,
+            )
+            return
+        for material in source.get_materials_of_field(field_name):
+            self._collect_subfield_average(
+                source,
+                field_name,
+                f"{field_name}_{material.name}",
+                quantity,
+                columns,
+                current_quantities,
+                subfield_requests,
+                mat_name=material.name,
+            )
+
+    def _collect_subfield_average(
+        self,
+        source: SimulationSource,
+        field_name: str,
+        prefix: str,
+        quantity: Quantity,
+        columns: list[tuple[str, Any]],
+        current_quantities: list[Quantity],
+        subfield_requests: list[_SubfieldRequest],
+        *,
+        mat_name: str | None = None,
+    ) -> None:
+        average = self._subfield_average(source, field_name, prefix, mat_name)
+        if average is None:
+            return
+        self._append_average_columns(columns, current_quantities, quantity, prefix, average)
+        subfield_requests.append(_SubfieldRequest(field_name, prefix, mat_name))
+
+    def _subfield_average(
+        self,
+        source: SimulationSource,
+        field_name: str,
+        prefix: str,
+        mat_name: str | None = None,
+    ) -> Any | None:
+        try:
+            with self._record_timing(f"average:{prefix}"):
+                average = source.get_subfield_average(field_name, mat_name)
+        except KeyError:
+            log.debug("Skipping unavailable subfield average %s", prefix)
+            average = None
+        self._record_source_average_timings(source, prefix)
+        return average
+
+    def _collect_initial_maxangle(
+        self,
+        source: SimulationSource,
+        columns: list[tuple[str, Any]],
+        current_quantities: list[Quantity],
+    ) -> bool:
+        maxangle_quantity = self.quantities_by_name.get("maxangle")
+        maxangle = self._maxangle_average(source)
+        if maxangle_quantity is None or maxangle is None:
+            return False
+        columns.append(("maxangle_m_Py", maxangle))
+        current_quantities.append(maxangle_quantity.sub_quantity("maxangle_m_Py"))
+        return True
+
+    def _maxangle_average(self, source: SimulationSource) -> float | None:
+        try:
+            with self._record_timing("average:maxangle_m_Py"):
+                maxangle = source.get_maxangle_average("m")
+        except KeyError:
+            log.debug("Skipping unavailable max-angle average for m")
+            maxangle = None
+        self._record_source_maxangle_timings(source, "maxangle_m_Py")
+        return maxangle
+
+    def _gather_existing_schema_data(self, source: SimulationSource) -> list[tuple[str, Any]]:
+        columns = self._base_columns(source)
+
+        for request in self._subfield_requests:
+            try:
+                with self._record_timing(f"average:{request.prefix}"):
+                    avg = source.get_subfield_average(request.field_name, request.mat_name)
+                self._record_source_average_timings(source, request.prefix)
+                if avg is None:
+                    continue
+            except KeyError:
+                self._record_source_average_timings(source, request.prefix)
+                log.debug("Skipping unavailable subfield average %s", request.prefix)
+                continue
+
+            self._append_average_columns(
+                columns,
+                None,
+                None,
+                request.prefix,
+                avg,
+            )
+
+        if self._writes_maxangle:
+            maxangle = self._maxangle_average(source)
+            if maxangle is not None:
+                columns.append(("maxangle_m_Py", maxangle))
+
+        return columns

simulation/hysteresis.py

@@ -0,0 +1,74 @@
+"""
+This file contains the implementation of the hysteresis method
+of the Simulation class.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from si.physical import SI
+from when import When
+
+from .clock import SimulationClock
+from .hysteresis_runner import (
+    _update_progress_file as _update_progress_file,  # noqa: F401
+)
+from .hysteresis_runner import (
+    simulation_hysteresis as simulation_hysteresis,
+)
+from .hysteresis_runner import (
+    simulation_relax as simulation_relax,
+)
+from .hysteresis_schedule import (
+    Action,
+    ScheduleInput,
+)
+from .hysteresis_schedule import (
+    _append_x_list as _append_x_list,  # noqa: F401
+)
+from .hysteresis_schedule import (
+    _join_save_and_do_lists as _join_save_and_do_lists,  # noqa: F401
+)
+from .hysteresis_schedule import (
+    _string_normalise as _string_normalise,  # noqa: F401
+)
+
+
+class _ConvergenceSource(Protocol):
+    def get_log(self) -> str: ...
+
+
+class HysteresisSimulation(Protocol):
+    name: str
+    clock: SimulationClock
+    convergence: _ConvergenceSource
+    action_abbreviations: dict[str, Action]
+    _restarting: bool
+    max_time_reached: SI
+
+    def simulation_hysteresis(
+        self,
+        H_ext_list: list[Any],
+        save: ScheduleInput | None = None,
+        do: ScheduleInput | None = None,
+        convergence_check: When | None = None,
+        progress_message_minimum_delay: float = 60.0,
+    ) -> None: ...
+
+    def load_restart_file(self, filename: str | None = None) -> None: ...
+
+    def do_next_stage(self, stage: int | None = None) -> None: ...
+
+    def set_H_ext(self, values: Any, unit: SI | None = None) -> None: ...
+
+    def reinitialise(self, initial_time: float | None = None) -> None: ...
+
+    def is_converged(self) -> bool: ...
+
+    def advance_time(
+        self,
+        target_time: SI,
+        max_it: int = -1,
+        exact_tstop: bool | None = None,
+    ) -> SI: ...

simulation/hysteresis_runner.py

@@ -0,0 +1,286 @@
+"""Execution loops for relaxation and multi-stage hysteresis."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from si.physical import SI
+from throttler import Throttler
+from when import When, at, every
+
+from .clock import SimulationClock
+from .hysteresis_schedule import (
+    CounterTriple,
+    ScheduleInput,
+    _join_save_and_do_lists,
+    _next_deltas,
+    _next_time,
+)
+
+log = logging.getLogger("nmag")
+_progress_throttler = Throttler()
+
+
+def _update_progress_file(
+    sim: Any,
+    H_ext: Any,
+    progress_file_name: str,
+    progress_message_minimum_delay: float,
+) -> None:
+    """
+    Writes the current simulation progress to a file, throttled
+    to a minimum delay.
+    """
+    if _progress_throttler.is_allowed("hysteresis_reporting", progress_message_minimum_delay):
+        try:
+            with open(progress_file_name, "w", encoding="utf-8") as f:
+                f.write(f"{time.asctime()}\n")
+                f.write(f"{sim.clock}\n")
+                f.write(f"{sim.convergence.get_log()}\n")
+
+            log.info(
+                f"it {sim.clock.step}, time {sim.clock.time_reached_si.dens_str()}; "
+                f"stage {sim.clock.stage}; H_ext={str(H_ext)}"
+            )
+        except Exception as e:
+            log.warning(f"Could not write progress file '{progress_file_name}'. Error: {e}")
+
+
+def simulation_relax(
+    self: Any,
+    H_applied: Any = None,
+    save: ScheduleInput | None = None,
+    do: ScheduleInput | None = None,
+    convergence_check: When | None = None,
+) -> None:
+    """
+    This method carries out the time integration of the LLG until
+    the system reaches a (metastable) equilibrium.
+    Internally, this uses the hysteresis() loop command.
+
+    (Docstring parameters omitted for brevity, they are unchanged)
+    """
+    if save is None:
+        save = [("averages", "fields", at("stage_end"))]
+    if do is None:
+        do = []
+    if convergence_check is None:
+        convergence_check = every("step", 5)
+
+    log.debug("Entering 'relax'")
+    fields = [H_applied]
+    log.debug(f"Calling hysteresis({fields})")
+    self.simulation_hysteresis(
+        fields,
+        save=save,
+        do=do,
+        convergence_check=convergence_check,
+    )
+
+
+def simulation_hysteresis(
+    self: Any,
+    H_ext_list: list[Any],
+    save: ScheduleInput | None = None,
+    do: ScheduleInput | None = None,
+    convergence_check: When | None = None,
+    progress_message_minimum_delay: float = 60.0,
+) -> None:
+    """
+    This method executes a simulation where the applied field
+    is set in sequence to the values specified in ``H_ext_list``.
+
+    (Full docstring omitted for brevity, it is unchanged)
+    """
+    save, do, convergence_check = _hysteresis_defaults(save, do, convergence_check)
+    log.debug(
+        f"simulation_hysteresis(): Entering with H_ext_list={H_ext_list}, "
+        f"save={save}, do={do}, convergence_check={convergence_check}"
+    )
+
+    thing_when_tuples = _scheduled_actions(self, save, do)
+    log.debug(f"simulation_hysteresis(): thing_when_tuples={thing_when_tuples}")
+    next_save_time = _initial_next_save_times(thing_when_tuples)
+    match_tolerances = _hysteresis_match_tolerances()
+    progress_file_name = f"{self.name}_progress.txt"
+    _prepare_hysteresis_run(self, progress_file_name)
+    stage: int | None = int(self.clock.stage)
+    self.clock.exit_hysteresis = False
+    for H_ext in H_ext_list[stage - 1 :]:
+        _prepare_hysteresis_stage(
+            self, H_ext, stage, thing_when_tuples, next_save_time, match_tolerances
+        )
+        stage = None
+        if _run_hysteresis_stage(
+            self,
+            H_ext,
+            thing_when_tuples,
+            next_save_time,
+            convergence_check,
+            match_tolerances,
+            progress_file_name,
+            progress_message_minimum_delay,
+        ):
+            return
+
+
+def _hysteresis_defaults(
+    save: ScheduleInput | None,
+    do: ScheduleInput | None,
+    convergence_check: When | None,
+) -> tuple[ScheduleInput, ScheduleInput, When]:
+    return (
+        [("averages", "fields", at("stage_end"))] if save is None else save,
+        [] if do is None else do,
+        every("step", 5) if convergence_check is None else convergence_check,
+    )
+
+
+def _scheduled_actions(self: Any, save: ScheduleInput, do: ScheduleInput) -> list[tuple[Any, When]]:
+    return _join_save_and_do_lists(save, do, predefined_actions=self.action_abbreviations)
+
+
+def _initial_next_save_times(
+    actions: list[tuple[Any, When]],
+) -> dict[str, CounterTriple | None]:
+    next_save_time: dict[str, CounterTriple | None] = {}
+    for what, _ in actions:
+        key = str(what)
+        if key in next_save_time:
+            raise ValueError(
+                "Error in optional argument 'save' or 'do' of method 'hysteresis': "
+                "the list of (thing_to_save, when) contains two or more specifications "
+                f"for thing_to_save = {key}. You should remove the duplicate entry and "
+                "eventually use the operator | (such as in: (thing_to_save, when1 | when2))."
+            )
+        next_save_time[key] = None
+    return next_save_time
+
+
+def _hysteresis_match_tolerances() -> dict[str, Any]:
+    negligible_time = SI(1e-20, "s")
+    return {"time": negligible_time, "stage_time": negligible_time}
+
+
+def _prepare_hysteresis_run(self: Any, progress_file_name: str) -> None:
+    if self._restarting:
+        log.info("Hysteresis loop: restarting from a previously saved configuration...")
+        self.load_restart_file()
+        self._restarting = False
+        return
+    log.info("Hysteresis loop: starting a new simulation.")
+    log.info(f"Hysteresis loop: check file '{progress_file_name}' for progress data")
+
+
+def _next_event_time(
+    event: When, clock: SimulationClock, tolerances: dict[str, Any]
+) -> CounterTriple:
+    return _next_time(event, clock, tols=tolerances)
+
+
+def _next_event_deltas(
+    event: When,
+    clock: SimulationClock,
+    tolerances: dict[str, Any],
+    suggest: CounterTriple | None = None,
+) -> CounterTriple:
+    return _next_deltas(event, clock, suggest=suggest, tols=tolerances)
+
+
+def _prepare_hysteresis_stage(
+    self: Any,
+    applied_field: Any,
+    stage: int | None,
+    actions: list[tuple[Any, When]],
+    next_save_time: dict[str, CounterTriple | None],
+    tolerances: dict[str, Any],
+) -> None:
+    log.info(f"hysteresis: starting new stage: field = {str(applied_field)}")
+    self.do_next_stage(stage=stage)
+    self.clock.stage_end = False
+    if applied_field is not None:
+        self.set_H_ext(applied_field)
+    self.reinitialise(initial_time=0)
+    for what, when in actions:
+        key = str(what)
+        next_save_time[key] = _next_event_time(when, self.clock, tolerances)
+        log.debug(f"hysteresis: will save {what} at {next_save_time[key]}")
+
+
+def _run_hysteresis_stage(
+    self: Any,
+    applied_field: Any,
+    actions: list[tuple[Any, When]],
+    next_save_time: dict[str, CounterTriple | None],
+    convergence_check: When,
+    tolerances: dict[str, Any],
+    progress_file_name: str,
+    progress_delay: float,
+) -> bool:
+    while True:
+        self.clock.stage_end = converged = self.is_converged()
+        deltas = _next_event_deltas(convergence_check, self.clock, tolerances)
+        deltas = _dispatch_scheduled_actions(
+            self,
+            actions,
+            next_save_time,
+            tolerances,
+            deltas,
+        )
+        if self.clock.exit_hysteresis:
+            log.debug(
+                "Exit from the hysteresis loop has been forced using the tag 'exit': exiting now!"
+            )
+            return True
+        if self.clock.stage_end:
+            log.debug(
+                f"Reached end of stage in hysteresis command, converged={converged}, exiting now!"
+            )
+            return False
+        _advance_hysteresis_stage(self, deltas, applied_field, progress_file_name, progress_delay)
+
+
+def _dispatch_scheduled_actions(
+    self: Any,
+    actions: list[tuple[Any, When]],
+    next_save_time: dict[str, CounterTriple | None],
+    tolerances: dict[str, Any],
+    deltas: CounterTriple,
+) -> CounterTriple:
+    for what, when in actions:
+        key = str(what)
+        next_time = _next_event_time(when, self.clock, tolerances)
+        if when.match_time(self.clock) or next_time != next_save_time[key]:
+            log.info(
+                f"hysteresis: saving {what} at id={self.clock.id},step={self.clock.step}.\n{self.clock}"
+            )
+            what(self)
+        next_save_time[key] = next_time
+        deltas = _next_event_deltas(when, self.clock, tolerances, suggest=deltas)
+    return deltas
+
+
+def _advance_hysteresis_stage(
+    self: Any,
+    deltas: CounterTriple,
+    applied_field: Any,
+    progress_file_name: str,
+    progress_delay: float,
+) -> None:
+    delta_step, delta_time, delta_real_time = deltas
+    target_time = (
+        self.max_time_reached if delta_time is None else self.clock.stage_time + delta_time
+    )
+    log.debug(
+        f"predicted advance: delta_step={delta_step}, delta_time={delta_time}, "
+        f"delta_real_time={delta_real_time}"
+    )
+    time_reached = self.advance_time(target_time, max_it=-1 if delta_step is None else delta_step)
+    if time_reached > 0.99 * self.max_time_reached:
+        raise RuntimeError(
+            f"Simulation time reached {self.max_time_reached}: "
+            "are you starting from a zero torque configuration?"
+        )
+    _update_progress_file(self, applied_field, progress_file_name, progress_delay)