Add new option "Hsteps" to HysteresisDriver

oommfc/drivers/driver.py

@@ -21,12 +21,11 @@ def __init__(self, **kwargs):
             self.autoselect_evolver = True
 
     @abc.abstractmethod
-    def _checkargs(self, kwargs) -> dict:
+    def _checkargs(self, kwargs):
         """Check drive keyword arguments.
 
-        This method can also update keyword arguments where required. It must return
-        a dict of all keyword arguments (initial or modified) that shall be used for the
-        simulation.
+        This method can also update keyword arguments where required. Changes must
+        happen in-place, i.e. `kwargs` must be modified directly.
         """
 
     def drive_kwargs_setup(self, drive_kwargs):
@@ -61,7 +60,7 @@ def drive_kwargs_setup(self, drive_kwargs):
             save additional data. Defaults to ``None``.
 
         """
-        drive_kwargs = self._checkargs(drive_kwargs)
+        self._checkargs(drive_kwargs)
         drive_kwargs.setdefault("fixed_subregions", None)
         drive_kwargs.setdefault("output_step", False)
         drive_kwargs.setdefault("n_threads", None)
@@ -103,7 +102,7 @@ def schedule_kwargs_setup(self, schedule_kwargs):
             save additional data. Defaults to ``None``.
 
         """
-        schedule_kwargs = self._checkargs(schedule_kwargs)
+        self._checkargs(schedule_kwargs)
         schedule_kwargs.setdefault("fixed_subregions", None)
         schedule_kwargs.setdefault("output_step", False)
         schedule_kwargs.setdefault("compute", None)

oommfc/drivers/hysteresisdriver.py

@@ -35,6 +35,19 @@ class HysteresisDriver(Driver):
     >>> hd._allowed_attributes
     [...]
 
+    4. How to define multiple steps with this driver.
+    >>> import micromagneticmodel as mm
+    >>> import oommfc as oc
+    >>> system = mm.examples.macrospin()
+    >>> sd = oc.HysteresisDriver()
+    >>> H = 1 / mm.consts.mu0
+    >>> sd.drive(system, Hsteps=[
+    ...    [(0, 0, 0), (0, 0, H), 10],
+    ...    [(0, 0, H), (0, 0, -H), 10],
+    ...    [(0, 0, -H), (0, 0, 0), 10],
+    ... ])
+    Running OOMMF ...
+
     """
 
     _allowed_attributes = [
@@ -59,12 +72,43 @@ class HysteresisDriver(Driver):
     ]
 
     def _checkargs(self, kwargs):
-        Hmin, Hmax, n = kwargs["Hmin"], kwargs["Hmax"], kwargs["n"]
-        for i in [Hmin, Hmax]:
-            if not isinstance(i, (list, tuple, np.ndarray)):
+        if any(item in kwargs for item in ["Hmin", "Hmax", "n"]) and "Hsteps" in kwargs:
+            # both Hsteps and (Hmin, Hmax, n) are defined, which is not allowed
+            msg = "Cannot define both (Hmin, Hmax, n) and Hsteps."
+            raise ValueError(msg)
+
+        if all(item in kwargs for item in ["Hmin", "Hmax", "n"]):
+            # case of a symmetric hysteresis simulation
+            # construct symmetric Hsteps from (Hmin, Hmax, n)
+            kwargs["Hsteps"] = [
+                [kwargs["Hmin"], kwargs["Hmax"], kwargs["n"]],
+                [kwargs["Hmax"], kwargs["Hmin"], kwargs["n"]],
+            ]
+            for key in ["Hmin", "Hmax", "n"]:
+                kwargs.pop(key)
+
+        if "Hsteps" in kwargs:
+            # case of a stepped hysteresis simulation
+            for step in kwargs["Hsteps"]:
+                if len(step) != 3:
+                    msg = (
+                        "Each list item in Hsteps must have 3 entries: Hstart, Hend, n."
+                    )
+                    raise ValueError(msg)
+                self._checkvalues(step[0], step[1], step[2])
+        else:
+            msg = (
+                "Cannot drive without a full definition of (Hmin, Hmax, n) xor Hsteps."
+            )
+            return ValueError(msg)
+
+    @staticmethod
+    def _checkvalues(Hmin, Hmax, n):
+        for item in [Hmin, Hmax]:
+            if not isinstance(item, (list, tuple, np.ndarray)):
                 msg = "Hmin and Hmax must have array_like values."
                 raise ValueError(msg)
-            if len(i) != 3:
+            if len(item) != 3:
                 msg = "Hmin and Hmax must have length 3."
                 raise ValueError(msg)
         if not isinstance(n, int):
@@ -73,7 +117,6 @@ def _checkargs(self, kwargs):
         if n - 1 <= 0:  # OOMMF counts steps, not points (n -> n-1)
             msg = f"Cannot drive with {n=}."
             raise ValueError(msg)
-        return kwargs
 
     def _check_system(self, system):
         """Checks the system has energy in it"""

oommfc/drivers/mindriver.py

@@ -57,7 +57,7 @@ class MinDriver(Driver):
     ]
 
     def _checkargs(self, kwargs):
-        return kwargs  # no kwargs should be checked
+        pass  # no kwargs should be checked
 
     def _check_system(self, system):
         """Checks the system has energy in it"""

oommfc/drivers/timedriver.py

@@ -66,7 +66,6 @@ def _checkargs(self, kwargs):
         if n <= 0:
             msg = f"Cannot drive with {n=}."
             raise ValueError(msg)
-        return kwargs
 
     def _check_system(self, system):
         """Checks the system has dynamics in it"""

oommfc/scripts/driver.py

@@ -29,12 +29,11 @@ def driver_script(
         mif += oc.scripts.evolver_script(driver.evolver)
 
         # Oxs_UZeeman
-        Hmin, Hmax, n = kwargs["Hmin"], kwargs["Hmax"], kwargs["n"]
         mif += "# OxS_UZeeman\n"
         mif += "Specify Oxs_UZeeman:hysteresis {\n"
         mif += "  Hrange {\n"
-        mif += "    {{ {} {} {} {} {} {} {} }}\n".format(*Hmin, *Hmax, n - 1)
-        mif += "    {{ {} {} {} {} {} {} {} }}\n".format(*Hmax, *Hmin, n - 1)
+        for Hstart, Hend, n in kwargs["Hsteps"]:
+            mif += "    {{ {} {} {} {} {} {} {} }}\n".format(*Hstart, *Hend, n - 1)
         mif += "  }\n"
         mif += "}\n\n"