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

llg3d/__init__.py

@@ -1 +1,6 @@
-__version__ = "1.4.1"
+"""Main llg3d package."""
+
+from .solver import LIB_AVAILABLE, rank, size, comm, status
+
+__version__ = "2.0.1"
+__all__ = ["LIB_AVAILABLE", "rank", "size", "comm", "status", "__version__"]

llg3d/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point to execute the llg3d module."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

llg3d/element.py

@@ -0,0 +1,134 @@
+"""Module containing the definition of the chemical elements."""
+
+from abc import ABC
+
+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(ABC):
+    """
+    Abstract class for chemical elements.
+
+    Args:
+        T: Temperature in Kelvin
+        H_ext: External magnetic field strength
+        g: Grid object representing the simulation grid
+        dt: Time step for the simulation
+    """
+
+    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:
+        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:
+            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):
+    """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):
+    """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):
+    """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,123 @@
+"""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,67 @@
+"""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:
+        arg_list: List of command line arguments
+    """
+    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,107 @@
+"""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}[{'█' * 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:
+        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

llg3d/post/__init__.py

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

llg3d/post/plot_results.py

@@ -0,0 +1,61 @@
+"""
+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():
+    """Main function to parse arguments and call the plot function."""
+    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/process.py

@@ -1,12 +1,14 @@
 #!/usr/bin/env python3
 """
-Post-processes a set of runs grouped into a `run.json` file or
-into a set of SLURM job arrays:
+Post-processes a set of runs.
+
+Runs are grouped into a `run.json` file or into a set of SLURM job arrays:
 
 1. Extracts result data,
 2. Plots the computed average magnetization against temperature,
 3. Interpolates the computed points using cubic splines,
-4. Determines the Curie temperature as the value corresponding to the minimal (negative) slope of the interpolated curve.
+4. Determines the Curie temperature as the value corresponding to the minimal (negative)
+    slope of the interpolated curve.
 """
 
 import json
@@ -17,14 +19,11 @@ from scipy.interpolate import interp1d
 
 
 class MagData:
-    """
-    Class to handle magnetization data and interpolation according to temperature
-    """
+    """Class to handle magnetization data and interpolation according to temperature."""
 
     n_interp = 200
 
     def __init__(self, job_dir: Path = None, run_file: Path = Path("run.json")) -> None:
-
         if job_dir:
             self.parentpath = job_dir
             data, self.run = self.process_slurm_jobs()
@@ -65,16 +64,18 @@ class MagData:
                     run = json.load(f)
                     # Adding temperature and averaging value to the data list
                     data.extend(
-                        [[float(T), res["m1_mean"]] for T, res in run["results"].items()]
+                        [
+                            [float(T), res["m1_mean"]]
+                            for T, res in run["results"].items()
+                        ]
                     )
             except FileNotFoundError:
-                print(f"Warning: {json_filename} file not found " f"in {jobdir.as_posix()}")
+                print(f"Warning: {json_filename} file not found in {jobdir.as_posix()}")
 
         data.sort()  # Sorting by increasing temperatures
 
         return np.array(data), run
 
-
     def process_json(json_filepath: Path) -> tuple[np.array, dict]:
         """
         Reads the run.json file and extracts result data.
@@ -98,8 +99,12 @@ class MagData:
     @property
     def T_Curie(self) -> float:
         """
-        Return the Curie temperature defined as the temperature at
-        which the magnetization is below 0.1
+        Return the Curie temperature.
+
+        It is defined as the temperature at which the magnetization is below 0.1.
+
+        Returns:
+            float: Curie temperature
         """
         i_max = np.where(0.1 - self.interp(self.T) > 0)[0].min()
-        return self.T[i_max]
+        return self.T[i_max]