Add new option "Hsteps" to HysteresisDriver

oommfc/drivers/driver.py

@@ -66,6 +66,7 @@ def drive_kwargs_setup(self, drive_kwargs):
         drive_kwargs.setdefault("output_step", False)
         drive_kwargs.setdefault("n_threads", None)
         drive_kwargs.setdefault("compute", None)
+        return drive_kwargs
 
     def schedule_kwargs_setup(self, schedule_kwargs):
         """Additional keyword arguments allowed for schedule.

oommfc/drivers/hysteresisdriver.py

@@ -35,6 +35,18 @@ class HysteresisDriver(Driver):
     >>> hd._allowed_attributes
     [...]
 
+    4. How to define multiple steps with this driver.
+    >>> import oommfc as oc
+    ...
+    >>> system = oc.System(name="my_system")
+    ...
+    >>> sd = oc.HysteresisDriver()
+    >>> sd.drive(system, Hsteps=[
+    >>>    [(0, 0, 0), (0, 0, 1), 10],
+    >>>    [(0, 0, 1), (0, 0, -1), 10],
+    >>>    [(0, 0, -1), (0, 0, 0), 10],
+    >>> ])
+
     """
 
     _allowed_attributes = [
@@ -59,12 +71,45 @@ 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"]],
+                ]
+            }
+
+        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)
+
+        return kwargs
+
+    @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 +118,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/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"