llg3d 2.0.1__py3-none-any.whl → 3.1.0__py3-none-any.whl

llg3d/parameters.py

@@ -1,75 +1,185 @@
-"""Parameters for the LLG3D simulation."""
+"""Parameters for the simulation."""
 
-import numpy as np
+from argparse import Action
+from dataclasses import asdict, dataclass, fields
+from typing import Any, Literal, NotRequired, TypedDict
 
-# Parameters: default value and description
-Parameter = dict[str, str | int | float | bool]  #: Type for a parameter
+from . import solvers
 
-parameters: dict[str, Parameter] = {
+# Type definitions for parameter names
+ElementType = Literal["Cobalt", "Iron", "Nickel"]
+SolverType = Literal["opencl", "mpi", "numpy", "jax"]
+PrecisionType = Literal["single", "double"]
+DeviceType = Literal["cpu", "gpu", "auto"]
+InitType = Literal["0", "dw"]
+
+
+@dataclass
+class RunParameters:
+    """
+    Store simulation parameters.
+
+    Example:
+        >>> params = RunParameters(element="Cobalt", N=1000)
+        >>> print(params)
+        element         : Cobalt
+        N               = 1000
+        dt              = 1e-14
+        Jx              = 300
+        Jy              = 21
+        Jz              = 21
+        dx              = 1e-09
+        T               = 1100
+        H_ext           = 0.0
+        init_type       : 0
+        result_file     : run.npz
+        start_averaging = 2000
+        n_mean          = 1
+        n_profile       = 0
+        solver          : numpy
+        precision       : double
+        blocking        = False
+        seed            = 12345
+        device          : auto
+        np              = 1
+    """
+
+    element: ElementType = "Cobalt"  #: Chemical element of the sample
+    N: int = 5000  #: Number of iterations
+    dt: float = 1.0e-14  #: Time step
+    Jx: int = 300  #: Number of points in x
+    Jy: int = 21  #: Number of points in y
+    Jz: int = 21  #: Number of points in z
+    dx: float = 1.0e-9  #: Step in x
+    T: float = 0.0  #: Temperature (K)
+    H_ext: float = 0.0  #: External field (A/m)
+    init_type: InitType = "0"  #: Initialization type
+    result_file: str = "run.npz"  #: Result file name
+    start_averaging: int = 4000  #: Start index of time average
+    n_mean: int = 1  #: Spatial average frequency (number of iterations)
+    n_profile: int = 0  #: x-profile save frequency (number of iterations)
+    solver: SolverType = "numpy" if solvers.size == 1 else "mpi"  #: Solver to use
+    precision: PrecisionType = "double"  #: Precision of the simulation
+    blocking: bool = False  #: Use blocking communications
+    seed: int = 12345  #: Random seed for temperature fluctuations
+    device: DeviceType = "auto"
+    profiling: bool = False  #: Enable profiling output
+    np: int = solvers.size  #: Number of processes (for MPI solver)
+
+    def as_dict(self) -> dict[str, Any]:
+        """
+        Convert RunParameters to a dictionary.
+
+        Returns:
+            Dictionary representation of the parameters
+        """
+        return asdict(self)
+
+    def __str__(self) -> str:
+        """Return solver information in a readable format."""
+        # Compute the width of the longest parameter name
+        width = max([len(field.name) for field in fields(self)])
+        s = ""
+        for field in fields(self):
+            value = getattr(self, field.name)
+            # the seprator is ":" for strings and "=" for others
+            sep = ":" if isinstance(value, str) else "="
+            s += "{0:<{1}} {2} {3}\n".format(field.name, width, sep, value)
+        return s
+
+
+DEFAULT_RUN_PARAMETERS = RunParameters()
+DRP = DEFAULT_RUN_PARAMETERS  #: Alias for default parameters
+
+ParameterValue = str | int | float | bool
+
+
+class ArgParameter(TypedDict):
+    """Metadata for a simulation parameter."""
+
+    help: str
+    default: ParameterValue
+    choices: NotRequired[Any]
+    action: NotRequired[str | type[Action]]
+    type: NotRequired[type]
+
+
+def lit_to_list(lit: Any) -> list[Any]:
+    """
+    Convert a Literal type to a list of its possible values.
+
+    Args:
+        lit: Literal type
+
+    Returns:
+        List of possible values
+    """
+    return list(lit.__args__)
+
+
+arg_parameters: dict[str, ArgParameter] = {
     "element": {
         "help": "Chemical element of the sample",
-        "default": "Cobalt",
-        "choices": ["Cobalt", "Iron", "Nickel"],
+        "default": DRP.element,
+        "choices": lit_to_list(ElementType),
+    },
+    "N": {"help": "Number of time iterations", "default": DRP.N},
+    "dt": {"help": "Time step", "default": DRP.dt},
+    "Jx": {"help": "Number of points in x", "default": DRP.Jx},
+    "Jy": {"help": "Number of points in y", "default": DRP.Jy},
+    "Jz": {"help": "Number of points in z", "default": DRP.Jz},
+    "dx": {"help": "Step in x", "default": DRP.dx},
+    "T": {"help": "Temperature (K)", "default": DRP.T},
+    "H_ext": {"help": "External field (A/m)", "default": DRP.H_ext},
+    "init_type": {
+        "help": "Type of initialization ('0' for uniform, 'dw' for domain wall)",
+        "default": DRP.init_type,
+        "choices": lit_to_list(InitType),
+    },
+    "result_file": {
+        "help": "Name of the npz result file",
+        "default": DRP.result_file,
+    },
+    "start_averaging": {
+        "help": "Start index of time average",
+        "default": DRP.start_averaging,
     },
-    "N": {"help": "Number of time iterations", "default": 5000},
-    "dt": {"help": "Time step", "default": 1.0e-14},
-    "Jx": {"help": "Number of points in x", "default": 300},
-    "Jy": {"help": "Number of points in y", "default": 21},
-    "Jz": {"help": "Number of points in z", "default": 21},
-    "dx": {"help": "Step in x", "default": 1.0e-9},
-    "T": {"help": "Temperature (K)", "default": 0.0},
-    "H_ext": {"help": "External field (A/m)", "default": 0.0 / (4 * np.pi * 1.0e-7)},
-    "start_averaging": {"help": "Start index of time average", "default": 4000},
     "n_mean": {
         "help": "Spatial average frequency (number of iterations)",
-        "default": 1,
+        "default": DRP.n_mean,
     },
     "n_profile": {
         "help": "x-profile save frequency (number of iterations)",
-        "default": 0,
+        "default": DRP.n_profile,
     },
     "solver": {
         "help": "Solver to use for the simulation",
-        "default": "numpy",
-        "choices": ["opencl", "mpi", "numpy", "jax"],
+        "default": DRP.solver,
+        "choices": lit_to_list(SolverType),
     },
     "precision": {
-        "help": "Precision of the simulation (single or double)",
-        "default": "double",
-        "choices": ["single", "double"],
+        "help": "Precision of the floating point (single or double)",
+        "default": DRP.precision,
+        "choices": lit_to_list(PrecisionType),
     },
     "blocking": {
-        "help": "Use blocking communications",
-        "default": False,
+        "help": "Use blocking communications (MPI solver only)",
+        "default": DRP.blocking,
         "action": "store_true",
     },
     "seed": {
         "help": "Random seed for temperature fluctuations",
-        "default": 12345,
+        "default": DRP.seed,
         "type": int,
     },
     "device": {
-        "help": "Device to use ('cpu', 'gpu', or 'auto')",
-        "default": "auto",
-        "type": str,
+        "help": "Device to use by the OpenCL solver",
+        "default": DRP.device,
+        "choices": lit_to_list(DeviceType),
     },
-}  #: simulation parameters
-
-
-def get_parameter_list(parameters: dict) -> str:
-    """
-    Returns parameter values as a string.
-
-    Args:
-        parameters: Dictionary of parameters parsed by argparse
-
-    Returns:
-        Formatted string of parameters
-    """
-    width = max([len(name) for name in parameters])
-    s = ""
-    for name, value in parameters.items():
-        # the seprator is ":" for strings and "=" for others
-        sep = ":" if isinstance(value, str) else "="
-        s += "{0:<{1}} {2} {3}\n".format(name, width, sep, value)
-    return s
+    "profiling": {
+        "help": "Enable profiling output (internal profiler)",
+        "default": DRP.profiling,
+        "action": "store_true",
+    },
+}  #: simulation CLI parameters

llg3d/post/__init__.py

@@ -1 +1 @@
-"""Post-processing tools for LLG3D."""
+"""Post-processing tools."""

llg3d/post/extract.py

@@ -0,0 +1,112 @@
+"""
+Extract scalar values from .npz result files.
+
+Use the ``llg3d.extract`` command line tool to extract scalar values from .npz result
+files:
+
+.. command-output:: llg3d.extract --help
+
+
+Extract the total execution time from a ``run.npz`` file:
+
+.. command-output:: llg3d.extract run.npz results/metrics/total_time
+    :cwd: ../execute
+
+
+Extract both the total execution time and the time per iteration:
+
+.. command-output:: llg3d.extract run.npz results/metrics/total_time \
+    results/metrics/time_per_ite
+    :cwd: ../execute
+"""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from llg3d.io import RunResults, load_results
+
+
+def _navigate(value: object, levels: list[str]):
+    """
+    Recursively navigate through nested structures using keys.
+
+    Tries subscript access (dicts/arrays) first, then attribute access (objects).
+
+    Args:
+        value: The current value to navigate.
+        levels: List of keys/attributes to navigate through.
+
+    Returns:
+        The final value after navigating through all levels.
+    """
+    if not levels:
+        return value
+
+    k = levels[0]
+    try:
+        # Try dict/array subscript access
+        next_value = value[k]  # type: ignore
+    except (TypeError, KeyError, IndexError):
+        # Fallback to attribute access
+        next_value = getattr(value, k)
+
+    return _navigate(next_value, levels[1:])
+
+
+ExtractedValue = float | int | str | bool | np.integer | np.floating
+
+
+def extract_values(npz_file: Path, *keys: str) -> list[ExtractedValue]:
+    """
+    Extract scalar values from a .npz file.
+
+    Args:
+        npz_file: Path to the .npz result file
+        *keys: tuple of keys of the scalar values to extract
+            (slash-separated for nested keys)
+
+    Returns:
+        The list of extracted scalar values
+
+    Raises:
+        ValueError: If one of the extracted values is not a scalar
+    """
+    results: RunResults = load_results(npz_file)
+    values: list[ExtractedValue] = []
+    for key in keys:
+        # Split path into levels
+        levels: list[str] = key.split("/")
+        raw_value = _navigate(results, levels)
+
+        # Handle numpy scalars and arrays with shape ()
+        if isinstance(raw_value, np.ndarray):
+            if raw_value.shape != ():
+                raise ValueError(f"Extracted value for key '{key}' is not a scalar.")
+            value = raw_value.item()  # Convert numpy scalar to Python scalar
+        else:
+            value = raw_value
+
+        if not isinstance(value, (float, int, str, bool, np.integer, np.floating)):
+            raise ValueError(f"Extracted value for key '{key}' is not a scalar.")
+        values.append(value)
+    return values
+
+
+def main():  # pragma: no cover
+    """Parse command line arguments and print simulation info."""
+    parser = argparse.ArgumentParser(
+        description="Extract scalar values from .npz result files.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("filename", help="Path to the .npz result file", type=Path)
+    parser.add_argument(
+        "keys",
+        nargs="+",
+        help="Key(s) of the scalar value(s) to extract (slash-separated for nested keys)",
+    )
+    args = parser.parse_args()
+
+    values = extract_values(args.filename, *args.keys)
+    print(" ".join(map(str, values)))

llg3d/post/info.py

@@ -0,0 +1,192 @@
+"""
+Dump simulation results from a .npz file.
+
+To browse the content of the ``run.npz`` file, use the ``llg3d.info`` command:
+
+.. command-output:: llg3d.info run.npz
+    :cwd: ../execute/
+
+The numpy arrays cans be previewed with more detailed information using the ``--verbose``
+option:
+
+.. command-output:: llg3d.info run.npz --verbose
+    :cwd: ../execute/
+
+"""
+
+import argparse
+import textwrap
+from pathlib import Path
+
+import numpy as np
+
+from ..io import Metrics, Records, RunResults, format_profiling_table, load_results
+
+INDENT = 4 * " "
+
+
+def get_array_memory(arr: np.ndarray) -> str:
+    """Return a human-readable string of the array memory size."""
+    nbytes: float | int = arr.nbytes
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if nbytes < 1024.0:
+            return f"{nbytes:.2f} {unit}"
+        nbytes /= 1024.0
+    return f"{nbytes:.2f} PB"
+
+
+def summarize_array(arr: np.ndarray) -> str:
+    """Return a summary of the array."""
+    s = f"""shape: {arr.shape}
+dtype: {arr.dtype}
+min: {arr.min():.6e}, max: {arr.max():.6e}
+mean: {arr.mean():.6e}, std: {arr.std():.6e}
+memory: {get_array_memory(arr)}
+"""
+    s += np.array2string(
+        arr,
+        max_line_width=120,
+        threshold=50,
+        edgeitems=2,
+        formatter={"float": lambda x: f"{x:.3e}"},
+    )
+    return textwrap.indent(s, INDENT)
+
+
+def dict_to_str(d: dict) -> str:
+    """
+    Convert a dictionary to a formatted string.
+
+    Right-aligns the values for better readability.
+    Skips empty dicts and empty lists.
+
+    Args:
+        d: The dictionary to convert.
+
+    Returns:
+        A formatted string representation of the dictionary.
+    """
+    # Filter out empty dicts and empty lists
+    filtered = {
+        k: v for k, v in d.items() if not (isinstance(v, (dict, list)) and not v)
+    }
+
+    if not filtered:
+        return ""
+
+    lines = []
+    max_key_length = max(len(str(key)) for key in filtered.keys())
+    for key, value in filtered.items():
+        lines.append(f"{key}: {' ' * (max_key_length - len(str(key)))}{value}")
+    return textwrap.indent("\n".join(lines), INDENT)
+
+
+def _format_array(arr: np.ndarray, verbose: bool) -> str:
+    """Format an array depending on verbosity."""
+    if verbose:
+        return summarize_array(arr)
+    else:
+        return textwrap.indent(f"shape: {arr.shape}, dtype: {arr.dtype}", INDENT)
+
+
+def _format_records(
+    records: Records | dict, verbose: bool, indent: int = 0
+) -> list[str]:
+    """Recursively format records section (nested dicts/arrays)."""
+    lines: list[str] = []
+    prefix = " " * indent
+    for key, value in records.items():
+        if isinstance(value, dict):
+            # Nested dict: recurse
+            lines.append(f"{prefix}{key}")
+            lines.extend(_format_records(value, verbose, indent + 4))
+        elif isinstance(value, np.ndarray):
+            # Numpy array: format accordingly
+            lines.append(f"{prefix}{key}")
+            lines.append(
+                textwrap.indent(_format_array(value, verbose), prefix + " " * 4)
+            )
+        else:
+            # Other types: just print key and value
+            lines.append(f"{prefix}{key}: {value}")
+    return lines
+
+
+def _format_metrics(metrics: Metrics) -> list[str]:
+    """
+    Format metrics data, handling profiling_stats specially.
+
+    Args:
+        metrics: Dictionary containing metrics data
+
+    Returns:
+        List of formatted lines to append
+    """
+    lines = []
+
+    # Extract metrics without profiling_stats
+    metrics_noprof = {k: v for k, v in metrics.items() if k != "profiling_stats"}
+    formatted = dict_to_str(metrics_noprof)
+    lines.append(formatted)
+
+    # Format profiling_stats as a table if present
+    if "profiling_stats" in metrics and metrics["profiling_stats"]:
+        lines.append("profiling_stats")
+        total_time = metrics.get("total_time")
+        lines.append(
+            textwrap.indent(
+                format_profiling_table(metrics["profiling_stats"], total_time), INDENT
+            )
+        )
+
+    return lines
+
+
+def get_info(filename: Path, verbose: bool = False) -> str:
+    """
+    Returns the simulation parameters and results from a .npz file.
+
+    Args:
+        filename: Path to the .npz result file
+        verbose: If True, includes detailed array information
+
+    Returns:
+        A formatted string with simulation information
+    """
+    run: RunResults = load_results(filename)
+
+    lines: list[str] = []
+
+    # Params
+    lines.append("params")
+    lines.append(dict_to_str(run.params.as_dict()))
+
+    # Metrics
+    lines.append("results/metrics")
+    lines.extend(_format_metrics(run.results["metrics"]))
+
+    # Observables
+    if "observables" in run.results:
+        observables = run.results["observables"]
+        lines.append("results/observables")
+        lines.append(dict_to_str(dict(observables)))
+
+    # Records
+    if "records" in run.results:
+        records = run.results["records"]
+        lines.append("results/records")
+        lines.extend(_format_records(records, verbose))
+
+    return "\n".join(lines)
+
+
+def main():  # pragma: no cover
+    """Parse command line arguments and print simulation info."""
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("filename", help="Path to the .npz result file", type=Path)
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    args = parser.parse_args()
+    print(get_info(args.filename, args.verbose))

llg3d/post/m1_vs_T.py

@@ -0,0 +1,107 @@
+"""
+Plot the magnetization vs temperature and determine the Curie temperature.
+
+Use the ``llg3d.m1_vs_T`` command line tool to plot the average magnetization versus
+temperature from multiple result files:
+
+.. command-output:: llg3d.m1_vs_T -h
+   :cwd: ../execute/temperatures
+
+When calling the tool on a selection of result files:
+
+.. command-output:: llg3d.m1_vs_T run_*.npz -i m1_vs_T.png
+   :cwd: ../execute/temperatures
+   :shell:
+
+.. image:: ../execute/temperatures/m1_vs_T.png
+   :alt: Magnetization versus temperature for multiple files
+"""
+
+from pathlib import Path
+
+import matplotlib
+import matplotlib.pyplot as plt
+
+from .process import MagTempData
+
+
+def plot_m1_vs_T(
+    mag_data: MagTempData,
+    image_filepath: Path | str | None = None,
+    show: bool = False,
+):
+    """
+    Plots the data (T, <m_1>).
+
+    Interpolates the values, calculates the Curie temperature, exports to PNG.
+
+    Args:
+        mag_data: Magnetization data object
+        image_filepath: Path to save the image
+          if None, the image will not be saved.
+        show: display the graph in a graphical window
+    """
+    print(f"T_Curie = {mag_data.T_Curie:.0f} K")
+    if not show:
+        matplotlib.use("Agg")  # Use non-interactive backend
+
+    fig, ax = plt.subplots()
+    fig.suptitle("Average magnetization vs Temperature")
+    params = mag_data.params
+    ax.set_title(
+        params["element"]
+        + rf", ${params['Jx']}\times{params['Jy']}\times{params['Jz']}$"
+        rf" ($dx = ${params['dx']})",
+        fontdict={"size": 10},
+    )
+    ax.plot(
+        mag_data.temperature,
+        mag_data.m1_mean,
+        "o",
+        markerfacecolor="white",
+        label=f"{params['solver']} computations",
+    )
+    ax.plot(
+        mag_data.temperature_interp,
+        mag_data.interp(mag_data.temperature_interp),
+        label="interpolation (PCHIP)",
+    )
+    ax.annotate(
+        "$T_{{Curie}} = {:.0f} K$".format(mag_data.T_Curie),
+        xy=(mag_data.T_Curie, 0.1),
+        xytext=(mag_data.T_Curie + 20, 0.1 + 0.01),
+    )
+    # Draw lines to indicate T_Curie
+    ax_ymin = ax.get_ylim()[0]
+    ax_ymax = ax.get_ylim()[1]
+    y_T_Curie = (0.1 - ax_ymin) / (ax_ymax - ax_ymin)
+    ax.axvline(x=mag_data.T_Curie, ymax=y_T_Curie, color="k", linestyle="--")
+    ax_xmin = ax.get_xlim()[0]
+    x_T_Curie = (mag_data.T_Curie - ax_xmin) / (ax.get_xlim()[1] - ax_xmin)
+    ax.axhline(y=0.1, xmax=x_T_Curie, color="k", linestyle="--")
+    # Mark the Curie point
+    ax.plot(mag_data.T_Curie, 0.1, color="k", marker="s", markerfacecolor="white")
+    ax.set_xlabel("Temperature [K]")
+    ax.set_ylabel("Magnetization")
+    ax.grid()
+    ax.legend()
+
+    if show:
+        plt.show()
+
+    if image_filepath is not None:
+        fig.savefig(image_filepath, dpi=300)
+        print(f"Written to {image_filepath}")
+
+
+def main():  # pragma: no cover
+    """Parses the command line to execute processing functions."""
+    from .utils import get_cli_args
+
+    args = get_cli_args(
+        description="Plot the magnetization vs temperature and determine the Curie temperature.",
+        default_image_filepath=Path("m1_vs_T.png"),
+    )
+
+    mag_data = MagTempData(*args.files)
+    plot_m1_vs_T(mag_data, image_filepath=args.image_filepath, show=args.show)