llg3d 1.4.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

llg3d/__init__.py

@@ -1 +1,4 @@
-__version__ = "1.4.0"
+from .solver import LIB_AVAILABLE, rank, size, comm, status
+
+__version__ = "2.0.0"
+__all__ = ["LIB_AVAILABLE", "rank", "size", "comm", "status", "__version__"]

llg3d/__main__.py

@@ -0,0 +1,6 @@
+# Enable to use llg3d as a module
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

llg3d/element.py

@@ -0,0 +1,128 @@
+r"""
+Module containing the definition of the chemical elements
+"""
+
+import numpy as np
+
+from .grid import Grid
+
+k_B = 1.38e-23  #: Boltzmann constant :math:`[J.K^{-1}]`
+mu_0 = 4 * np.pi * 1.0e-7  #: Vacuum permeability :math:`[H.m^{-1}]`
+gamma = 1.76e11  #: Gyromagnetic ratio :math:`[rad.s^{-1}.T^{-1}]`
+
+
+class Element:
+    """Abstract class for chemical elements"""
+
+    A = 0.0
+    K = 0.0
+    lambda_G = 0.0
+    M_s = 0.0
+    a_eff = 0.0
+    anisotropy: str = ""
+
+    def __init__(self, T: float, H_ext: float, g: Grid, dt: float) -> None:
+        """Initializes the Element class with given parameters
+
+        Args:
+            T: Temperature in Kelvin
+            H_ext: External magnetic field strength
+            g: Grid object representing the simulation grid
+            dt: Time step for the simulation
+        """
+        self.H_ext = H_ext
+        self.g = g
+        self.dt = dt
+        self.gamma_0 = gamma * mu_0  #: Rescaled gyromagnetic ratio [mA^-1.s^-1]
+
+        # --- Characteristic Scales ---
+        self.coeff_1 = self.gamma_0 * 2.0 * self.A / (mu_0 * self.M_s)
+        self.coeff_2 = self.gamma_0 * 2.0 * self.K / (mu_0 * self.M_s)
+        self.coeff_3 = self.gamma_0 * H_ext
+
+        # corresponds to the temperature actually put into the random field
+        T_simu = T * self.g.dx / self.a_eff
+        # calculation of the random field related to temperature
+        # (we only take the volume over one mesh)
+        h_alea = np.sqrt(
+            2 * self.lambda_G * k_B / (self.gamma_0 * mu_0 * self.M_s * self.g.dV)
+        )
+        H_alea = h_alea * np.sqrt(T_simu) * np.sqrt(1.0 / self.dt)
+        self.coeff_4 = H_alea * self.gamma_0
+
+    def get_CFL(self) -> float:
+        """
+        Returns the value of the CFL
+
+        Returns:
+            float: The CFL value
+        """
+        return self.dt * self.coeff_1 / self.g.dx**2
+
+    def to_dict(self) -> dict:
+        """
+        Export element parameters to a dictionary for JAX JIT compatibility
+
+        Returns:
+            Dictionary containing element parameters needed for computations
+        """
+        # Map anisotropy string to integer for JIT compatibility
+        aniso_map = {"uniaxial": 0, "cubic": 1}
+
+        return {
+            "coeff_1": self.coeff_1,
+            "coeff_2": self.coeff_2,
+            "coeff_3": self.coeff_3,
+            "coeff_4": self.coeff_4,
+            "lambda_G": self.lambda_G,
+            "anisotropy": aniso_map[self.anisotropy],
+            "gamma_0": self.gamma_0,
+        }
+
+
+class Cobalt(Element):
+    A = 30.0e-12  #: Exchange constant :math:`[J.m^{-1}]`
+    K = 520.0e3  #: Anisotropy constant :math:`[J.m^{-3}]`
+    lambda_G = 0.5  #: Damping parameter :math:`[1]`
+    M_s = 1400.0e3  #: Saturation magnetization :math:`[A.m^{-1}]`
+    a_eff = 0.25e-9  #: Effective lattice constant :math:`[m]`
+    anisotropy = "uniaxial"  #: Type of anisotropy (e.g., "uniaxial", "cubic")
+
+
+class Iron(Element):
+    A = 21.0e-12  #: Exchange constant :math:`[J.m^{-1}]`
+    K = 48.0e3  #: Anisotropy constant :math:`[J.m^{-3}]`
+    lambda_G = 0.5  #: Damping parameter :math:`[1]`
+    M_s = 1700.0e3  #: Saturation magnetization :math:`[A.m^{-1}]`
+    a_eff = 0.286e-9  #: Effective lattice constant :math:`[m]`
+    anisotropy = "cubic"  #: Type of anisotropy (e.g., "uniaxial", "cubic")
+
+
+class Nickel(Element):
+    A = 9.0e-12  #: Exchange constant :math:`[J.m^{-1}]`
+    K = -5.7e3  #: Anisotropy constant :math:`[J.m^{-3}]`
+    lambda_G = 0.5  #: Damping parameter :math:`[1]`
+    M_s = 490.0e3  #: Saturation magnetization :math:`[A.m^{-1}]`
+    a_eff = 0.345e-9  #: Effective lattice constant :math:`[m]`
+    anisotropy = "cubic"  #: Type of anisotropy (e.g., "uniaxial", "cubic")
+
+
+def get_element_class(element_name: str | type[Element]) -> type[Element]:
+    """
+    Get the class of the chemical element by its name.
+
+    Args:
+        element_name: The name of the element or its class
+
+    Returns:
+        The class of the element
+
+    Raises:
+        ValueError: If the element is not found
+    """
+    if isinstance(element_name, type):
+        return element_name
+    for cls in Element.__subclasses__():
+        if cls.__name__ == element_name:
+            return cls
+    raise ValueError(f"Element '{element_name}' not found in {__file__}.")

llg3d/grid.py

@@ -0,0 +1,126 @@
+"""
+Module to define the grid for the simulation
+"""
+
+from dataclasses import dataclass
+import numpy as np
+
+from .solver import rank, size
+
+
+@dataclass
+class Grid:
+    """Stores grid data"""
+
+    # Parameter values correspond to the global grid
+    Jx: int  #: number of points in x direction
+    Jy: int  #: number of points in y direction
+    Jz: int  #: number of points in z direction
+    dx: float  #: grid spacing in x direction
+
+    def __post_init__(self) -> None:
+        """Compute grid characteristics"""
+        self.dy = self.dz = self.dx  # Setting dx = dy = dz
+        self.Lx = (self.Jx - 1) * self.dx
+        self.Ly = (self.Jy - 1) * self.dy
+        self.Lz = (self.Jz - 1) * self.dz
+        # shape of the local array to the process
+        self.dims = self.Jx // size, self.Jy, self.Jz
+        # elemental volume of a cell
+        self.dV = self.dx * self.dy * self.dz
+        # total volume
+        self.V = self.Lx * self.Ly * self.Lz
+        # total number of points
+        self.ntot = self.Jx * self.Jy * self.Jz
+        self.ncell = (self.Jx - 1) * (self.Jy - 1) * (self.Jz - 1)
+
+    def __str__(self) -> str:
+        """Print grid information"""
+
+        header = "\t\t".join(("x", "y", "z"))
+        s = f"""\
+\t{header}
+J\t{self.Jx}\t\t{self.Jy}\t\t{self.Jz}
+L\t{self.Lx:.08e}\t{self.Ly:.08e}\t{self.Lz:.08e}
+d\t{self.dx:.08e}\t{self.dy:.08e}\t{self.dz:.08e}
+
+dV    = {self.dV:.08e}
+V     = {self.V:.08e}
+ntot  = {self.ntot:d}
+ncell = {self.ncell:d}
+"""
+        return s
+
+    def get_filename(
+        self, T: float, name: str = "m1_mean", extension: str = "txt"
+    ) -> str:
+        """
+        Returns the output file name for a given temperature
+
+        Args:
+            T: temperature
+            name: file name
+            extension: file extension
+
+        Returns:
+            file name
+
+        >>> g = Grid(Jx=300, Jy=21, Jz=21, dx=1.e-9)
+        >>> g.get_filename(1100)
+        'm1_mean_T1100_300x21x21.txt'
+        """
+        suffix = f"T{int(T)}_{self.Jx}x{self.Jy}x{self.Jz}"
+        return f"{name}_{suffix}.{extension}"
+
+    def get_mesh(
+        self, local: bool = True, dtype=np.float64
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Returns a meshgrid of the coordinates.
+
+        Args:
+            local: if True, returns the local coordinates,
+                   otherwise the global coordinates
+            dtype: data type of the coordinates)
+
+        Returns:
+            tuple of 3D arrays with the coordinates
+        """
+        x_global = np.linspace(0, self.Lx, self.Jx, dtype=dtype)  # global coordinates
+        y = np.linspace(0, self.Ly, self.Jy, dtype=dtype)
+        z = np.linspace(0, self.Lz, self.Jz, dtype=dtype)
+        if local:
+            x_local = np.split(x_global, size)[rank]  # local coordinates
+            return np.meshgrid(x_local, y, z, indexing="ij")
+        else:
+            return np.meshgrid(x_global, y, z, indexing="ij")
+
+    def to_dict(self) -> dict:
+        """
+        Export grid parameters to a dictionary for JAX JIT compatibility
+
+        Returns:
+            Dictionary containing grid parameters needed for computations
+        """
+        return {
+            "dx": self.dx,
+            "dy": self.dy,
+            "dz": self.dz,
+            "Jx": self.Jx,
+            "Jy": self.Jy,
+            "Jz": self.Jz,
+            "dV": self.dV,
+        }
+
+    def get_laplacian_coeff(self) -> tuple[float, float, float, float]:
+        """
+        Returns the coefficients for the laplacian computation
+
+        Returns:
+            Tuple of coefficients (dx2_inv, dy2_inv, dz2_inv, center_coeff)
+        """
+        dx2_inv = 1 / self.dx**2
+        dy2_inv = 1 / self.dy**2
+        dz2_inv = 1 / self.dz**2
+        center_coeff = -2 * (dx2_inv + dy2_inv + dz2_inv)
+        return dx2_inv, dy2_inv, dz2_inv, center_coeff

llg3d/main.py

@@ -0,0 +1,66 @@
+"""
+Define a CLI for the llg3d package.
+"""
+
+import argparse
+
+
+from . import rank, size, LIB_AVAILABLE
+from .parameters import parameters, get_parameter_list
+from .simulation import Simulation
+
+if LIB_AVAILABLE["mpi4py"]:
+    # Use the MPI version of the ArgumentParser
+    from .solver.mpi import ArgumentParser
+else:
+    # Use the original version of the ArgumentParser
+    from argparse import ArgumentParser
+
+
+def parse_args(args: list[str] | None) -> argparse.Namespace:
+    """
+    Argument parser for llg3d.
+    Automatically adds arguments from the parameter dictionary.
+
+    Returns:
+        argparse.Namespace: Parsed arguments
+    """
+    parser = ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    if size > 1:
+        parameters["solver"]["default"] = "mpi"
+
+    # Automatically add arguments from the parameter dictionary
+    for name, parameter in parameters.items():
+        if "action" not in parameter:
+            parameter["type"] = type(parameter["default"])
+        parser.add_argument(f"--{name}", **parameter)
+
+    return parser.parse_args(args)
+
+
+def main(arg_list: list[str] = None):
+    """
+    Evaluates the command line and runs the simulation
+    """
+
+    args = parse_args(arg_list)
+
+    if size > 1 and args.solver != "mpi":
+        raise ValueError(f"Solver method {args.solver} is not compatible with MPI.")
+    if args.solver == "mpi" and not LIB_AVAILABLE["mpi4py"]:
+        raise ValueError(
+            "The MPI solver method requires to install the mpi4py package, "
+            "for example using pip: pip install mpi4py"
+        )
+
+    if rank == 0:
+        # Display parameters as a list
+        print(get_parameter_list(vars(args)))
+
+    simulation = Simulation(vars(args))
+    simulation.run()
+    simulation.save()

llg3d/output.py

@@ -0,0 +1,108 @@
+"""
+Utility functions for LLG3D
+"""
+
+import json
+import sys
+from typing import Iterable, TextIO
+
+from .solver import rank
+from .grid import Grid
+
+
+def progress_bar(it: Iterable, prefix: str = "", size: int = 60, out: TextIO = sys.stdout):
+    """
+    Displays a progress bar
+
+    (Source: https://stackoverflow.com/a/34482761/16593179)
+
+    Args:
+        it: Iterable object to iterate over
+        prefix: Prefix string for the progress bar
+        size: Size of the progress bar (number of characters)
+        out: Output stream (default is sys.stdout)
+    """
+
+    count = len(it)
+
+    def show(j):
+        x = int(size * j / count)
+        if rank == 0:
+            print(
+                f"{prefix}[{u'█'*x}{('.'*(size-x))}] {j}/{count}",
+                end="\r",
+                file=out,
+                flush=True,
+            )
+
+    show(0)
+    for i, item in enumerate(it):
+        yield item
+        # To avoid slowing down the computation, we do not display at every iteration
+        if i % 5 == 0:
+            show(i + 1)
+    show(i + 1)
+    if rank == 0:
+        print("\n", flush=True, file=out)
+
+
+def write_json(json_file: str, run: dict):
+    """
+    Writes the run dictionary to a JSON file
+
+    Args:
+        json_file: Name of the JSON file
+        run: Dictionary containing the run information
+    """
+    with open(json_file, "w") as f:
+        json.dump(run, f, indent=4)
+
+
+def get_output_files(g: Grid, T: float, n_mean: int, n_profile: int) -> tuple:
+    """
+    Open files and list them
+
+    Args:
+        g: Grid object
+        T: temperature
+        n_mean: Number of iterations for integral output
+        n_profile: Number of iterations for profile output
+
+    Returns:
+        - a file handler for storing m space integral over time
+        - a file handler for storing x-profiles of m_i
+        - a list of output filenames
+    """
+    f_mean = None
+    f_profiles = None
+    output_filenames = []
+    if n_mean != 0:
+        output_filenames.append(g.get_filename(T, extension="txt"))
+    if n_profile != 0:
+        output_filenames.extend(
+            [g.get_filename(T, name=f"m{i + 1}", extension="npy") for i in range(3)]
+        )
+    if rank == 0:
+        if n_mean != 0:
+            f_mean = open(output_filenames[0], "w")  # integral of m1
+        if n_profile != 0:
+            f_profiles = [
+                open(output_filename, "wb") for output_filename in output_filenames[1:]
+            ]  # x profiles of m_i
+
+    return f_mean, f_profiles, output_filenames
+
+
+def close_output_files(f_mean: TextIO, f_profiles: list[TextIO] = None):
+    """
+    Close all output files
+
+    Args:
+        f_mean: file handler for storing m space integral over time
+        f_profiles: file handlers for storing x-profiles of m_i
+    """
+    if f_mean is not None:
+        f_mean.close()
+    if f_profiles is not None:
+        for f_profile in f_profiles:
+            f_profile.close()

llg3d/parameters.py

@@ -0,0 +1,75 @@
+"""Parameters for the LLG3D simulation."""
+
+import numpy as np
+
+# Parameters: default value and description
+Parameter = dict[str, str | int | float | bool]  #: Type for a parameter
+
+parameters: dict[str, Parameter] = {
+    "element": {
+        "help": "Chemical element of the sample",
+        "default": "Cobalt",
+        "choices": ["Cobalt", "Iron", "Nickel"],
+    },
+    "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,
+    },
+    "n_profile": {
+        "help": "x-profile save frequency (number of iterations)",
+        "default": 0,
+    },
+    "solver": {
+        "help": "Solver to use for the simulation",
+        "default": "numpy",
+        "choices": ["opencl", "mpi", "numpy", "jax"],
+    },
+    "precision": {
+        "help": "Precision of the simulation (single or double)",
+        "default": "double",
+        "choices": ["single", "double"],
+    },
+    "blocking": {
+        "help": "Use blocking communications",
+        "default": False,
+        "action": "store_true",
+    },
+    "seed": {
+        "help": "Random seed for temperature fluctuations",
+        "default": 12345,
+        "type": int,
+    },
+    "device": {
+        "help": "Device to use ('cpu', 'gpu', or 'auto')",
+        "default": "auto",
+        "type": str,
+    },
+}  #: simulation parameters
+
+
+def get_parameter_list(parameters: dict) -> str:
+    """
+    Returns parameter values as a string
+
+    Args:
+        d: Dictionary of parameters parsed by argparse
+
+    Returns:
+        str: 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

llg3d/post/plot_results.py

@@ -0,0 +1,65 @@
+"""
+Plot 1D curves from several files
+
+Usage:
+
+python plot_results.py file1.txt
+or
+python plot_results.py file1.txt file2.txt file3.txt
+
+"""
+
+import argparse
+from matplotlib import pyplot as plt
+import numpy as np
+
+
+DEFAULT_OUTPUT_FILE = "results.png"
+
+
+def plot(*files: tuple[str], output_file: str = DEFAULT_OUTPUT_FILE):
+    """
+    Plot the results from the given files.
+
+    Args:
+        files (tuple[str]): Paths to the result files.
+        output_file (str): Path to the output image file.
+    """
+
+    fig, ax = plt.subplots()
+    for file in files:
+        if not file.endswith(".txt"):
+            raise ValueError(f"File {file} does not end with .txt")
+        data = np.loadtxt(file)
+        ax.plot(data[:, 0], data[:, 1], label=file)
+
+    ax.set_xlabel("time")
+    ax.set_ylabel(r"$<m_1>$")
+    ax.legend()
+    ax.set_title(r"Space average of $m_1$ according to time")
+    fig.savefig(output_file)
+    print(f"Written to {output_file}")
+    plt.show()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Plot results from one or more files."
+    )
+    parser.add_argument(
+        "files", nargs="+", type=str, help="Path to the result files."
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        default=DEFAULT_OUTPUT_FILE,
+        help=f"Path to the output image file (default: {DEFAULT_OUTPUT_FILE}).",
+    )
+    args = parser.parse_args()
+
+    plot(*args.files, output_file=args.output)
+
+
+if __name__ == "__main__":
+    main()

llg3d/post/temperature.py

@@ -7,7 +7,6 @@ import argparse
 from pathlib import Path
 
 import matplotlib.pyplot as plt
-import numpy as np
 
 from .process import MagData
 

llg3d/simulation.py

@@ -0,0 +1,104 @@
+"""
+Define the Simulation class.
+
+Example usage:
+
+    >>> from llg3d.main import Simulation
+    >>> from llg3d.parameters import parameters
+    >>> run_parameters = {name: value["default"] for name, value in parameters.items()}
+    >>> sim = Simulation(run_parameters)
+    >>> sim.run()
+    >>> sim.save()
+
+"""
+
+import inspect
+
+from . import rank, size
+from .element import get_element_class
+from .parameters import Parameter
+from .output import write_json
+
+
+class Simulation:
+    """
+    Class to encapsulate the simulation logic.
+    """
+
+    json_file = "run.json"  #: JSON file to store the results
+
+    def __init__(self, params: dict[str, Parameter]):
+        """
+        Initializes the simulation with parameters.
+
+        Args:
+            params: Dictionary of simulation parameters.
+        """
+        self.params: dict[str, Parameter] = params.copy()  #: simulation parameters
+        self.simulate: callable = self._get_simulate_function_from_name(
+            self.params["solver"]
+        )  #: simulation function imported from the solver module
+        self.total_time: None | float = None  #: total simulation time
+        self.filenames: list[str] = []  #: list of output filenames
+        self.m1_mean: None | float = None  #: space and time average of m1
+        self.params["np"] = size  # Add a parameter for the number of processes
+        # Reference the element class from the element string
+        self.params["element_class"] = get_element_class(params["element"])
+
+    def run(self):
+        """
+        Runs the simulation and store the results.
+        """
+        self.total_time, self.filenames, self.m1_mean = self.simulate(**self.params)
+
+    def _get_simulate_function_from_name(self, name: str) -> callable:
+        """
+        Retrieves the simulation function for a given solver name.
+
+        Args:
+            name: Name of the solver
+
+        Returns:
+            callable: The simulation function
+
+        Example:
+
+            >>> simulate = self.get_simulate_function_from_name("mpi")
+
+            Will return the `simulate` function from the `llg3d.solver.mpi` module.
+        """
+
+        module = __import__(f"llg3d.solver.{name}", fromlist=["simulate"])
+        return inspect.getattr_static(module, "simulate")
+
+    def save(self):
+        """
+        Saves the results of the simulation to a JSON file.
+        """
+        params = self.params.copy()  # save the parameters
+        del params["element_class"]  # remove class object before serialization
+        if rank == 0:
+            results = {"total_time": self.total_time}
+            # Export the integral of m1
+            if len(self.filenames) > 0:
+                results["integral_file"] = self.filenames[0]
+                print(f"Integral of m1 in {self.filenames[0]}")
+            # Export the x-profiles of m1, m2 and m3
+            for i, filename in enumerate(self.filenames[1:]):
+                results[f"xprofile_m{i}"] = filename
+                print(f"x-profile of m{i} in {filename}")
+
+            print(
+                f"""\
+N iterations      = {params["N"]}
+total_time [s]    = {self.total_time:.03f}
+time/ite [s/iter] = {self.total_time / params["N"]:.03e}\
+"""
+            )
+            # Export the mean of m1
+            if params["N"] > params["start_averaging"]:
+                print(f"m1_mean           = {self.m1_mean:e}")
+                results["m1_mean"] = float(self.m1_mean)
+
+            write_json(self.json_file, {"params": params, "results": results})
+            print(f"Summary in {self.json_file}")