Merge branch 'main' of https://github.com/magpylib/magpylib into refa…

…ctor-getBH
magpylib · OrtnerMichael · Jul 26, 2022 · Mar 21, 2022 · Mar 22, 2022 · Mar 22, 2022
commit 249f247ccb950bbd18fbf576f283521d175bfafd
diff --git a/docs/_pages/page_01_introduction.md b/docs/_pages/page_01_introduction.md
@@ -541,7 +541,7 @@ One central motivation behind the `Collection` class is enabling users to build
 
 **User-defined 3D models** (traces) for any object that will be displayed by `show`, can be stored in `style.model3d.data`. A trace itself is a dictionary that contains all information necessary for plotting, and can be added with the method `style.model3d.data.add_trace`. In the example gallery {ref}`examples-3d-models` it is explained how to create custom traces with standard plotting backends such as `scatter3d` or `mesh3d` in Plotly, or `plot`, `plot_surface` and `plot_trisurf` in Matplotlib. Some pre-defined models are also provided for easy parts visualization.
 
-**User-defined source objects** are easily realized with the `CustomSource` class. Such a custom source object is provided with a user-defined field computation function, that is stored in the attribute `field_func` and is used when `getB` and `getH` are called. The provided function must accept a `field` argument as a string (`'B'` or `'H'`) and an `observer` array with shape (n,3), and return the field with a similar shape. Details on working with custom sources are given in {ref}`examples-custom-source-objects`.
+**User-defined source objects** are easily realized with the `CustomSource` class. Such a custom source object is provided with a user-defined field computation function, that is stored in the attribute `field_func` and is used when `getB` and `getH` are called. Similar to core functions, `field_func` must have the two positional arguments `field` (can be `'B'` or `'H'`) and `observers` (must accept ndarrays of shape (n,3)), and return the respective fields in units of \[mT\] and \[kA/m\] in the same shape. Details on working with custom sources are given in {ref}`examples-custom-source-objects`.
 
 While each of these features can be used individually, the combination of the two (own source class with own 3D representation) enables a high level of customization in Magpylib. Such user-defined objects will feel like native Magpylib objects and can be used in combination with all other features, which is demonstrated in the following example:
 
@@ -550,12 +550,11 @@ import numpy as np
 import plotly.graph_objects as go
 import magpylib as magpy
 
-# define B-field function for custom source
-def easter_field(field, observer):
+# define B/H field function for custom source
+def easter_field(field, observers):
     """ points in z-direction and decays with 1/r^3"""
-    if field=='B':
-        dist = np.linalg.norm(observer, axis=1)
-        return np.c_[np.zeros((len(observer),2)), 1/dist**3]
+    dist = np.linalg.norm(observers, axis=1)
+    return np.c_[np.zeros((len(observers),2)), 1/dist**3]
 
 # create custom source
 egg = magpy.misc.CustomSource(

diff --git a/docs/examples/examples_04_custom_source.md b/docs/examples/examples_04_custom_source.md
@@ -14,22 +14,21 @@ kernelspec:
 (examples-custom-source-objects)=
 # Custom source objects
 
-The class `CustomSource` allows users to integrate their own custom-objects into the Magpylib interface. The `field_func` argument can be provided with a function that is called with `getB` and `getH`.
-
-This custom field function is treated like a core functions. It must accept a `field` argument (`'B'` or `'H'`), an `observer` argument (array_like, shape (n,3)) and return the respective field with a similar shape. A fundamental example how to create a custom source object is shown below:
+The class `CustomSource` allows users to integrate their own custom-object field computation into the Magpylib interface. For this, the argument `field_func` must be provided with a function that is then automatically called with `getB` and `getH`. This custom field function is treated like a core function. It must have the positional arguments `field` (with values `'B'` or `'H'`), and `observers` (must accept array_like, shape (n,3)) and return the B-field in units of \[mT\] and the H-field in units of \[kA/m\] with a similar shape. A fundamental example how to create a custom source object is shown below:
 
 ```{code-cell} ipython3
 import numpy as np
 import magpylib as magpy
 
 # define field function
-def custom_field(field, observer):
+def custom_field(field, observers):
     """ user defined custom field
     position input: array_like, shape (n,3)
     returns: B-field, ndarray, shape (n,3)
     """
     if field=='B':
-        return np.array(observer)*2
+        return np.array(observers)*2
+    return np.array(observers)
 
 # custom source
 source = magpy.misc.CustomSource(field_func=custom_field)
@@ -68,7 +67,7 @@ trace_pole = magpy.graphics.model3d.make_Ellipsoid(
 # combine four monopole custom sources into a quadrupole collection
 def create_pole(charge):
     """ create a monopole object"""
-    field = lambda field, observer: monopole_field(charge, observer)
+    field = lambda field, observers: monopole_field(charge, observers)
     monopole = magpy.misc.CustomSource(
         field_func=field,
         style_model3d_showdefault=False,

diff --git a/docs/examples/examples_22_field_interpolation.md b/docs/examples/examples_22_field_interpolation.md
@@ -69,9 +69,8 @@ def interpolate_field(data, method="linear", bounds_error=False, fill_value=np.n
         rgi = RegularGridInterpolator((X, Y, Z), f.reshape(nx, ny, nz), **kwargs)
         field_interp.append(rgi)
 
-    def field_func(field, observer):
-        if field=='B':
-            return np.array([field(observer) for field in field_interp]).T
+    def field_func(field, observers):
+        return np.array([f(observers) for f in field_interp]).T
     return field_func
 ```
 

diff --git a/magpylib/_src/fields/field_BH_cuboid.py b/magpylib/_src/fields/field_BH_cuboid.py
@@ -8,7 +8,7 @@
 
 def magnet_cuboid_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     magnetization: np.ndarray,
     dimension: np.ndarray) -> np.ndarray:
     """Magnetic field of a homogeneously magnetized cuboid.
@@ -22,7 +22,7 @@ def magnet_cuboid_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     magnetization: ndarray, shape (n,3)

diff --git a/magpylib/_src/fields/field_BH_cylinder.py b/magpylib/_src/fields/field_BH_cylinder.py
@@ -204,7 +204,7 @@ def fieldH_cylinder_diametral(
 # ON INTERFACE
 def magnet_cylinder_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     magnetization: np.ndarray,
     dimension: np.ndarray,
     ) -> np.ndarray:
@@ -219,7 +219,7 @@ def magnet_cylinder_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     magnetization: ndarray, shape (n,3)

diff --git a/magpylib/_src/fields/field_BH_cylinder_segment.py b/magpylib/_src/fields/field_BH_cylinder_segment.py
@@ -1351,7 +1351,7 @@ def magnet_cylinder_segment_core(
 
 def magnet_cylinder_segment_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     magnetization: np.ndarray,
     dimension: np.ndarray,
     ) -> np.ndarray:
@@ -1366,7 +1366,7 @@ def magnet_cylinder_segment_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     magnetization: ndarray, shape (n,3)

diff --git a/magpylib/_src/fields/field_BH_dipole.py b/magpylib/_src/fields/field_BH_dipole.py
@@ -8,7 +8,7 @@
 
 def dipole_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     moment: np.ndarray,
     ) -> np.ndarray:
     """Magnetic field of a dipole moment.
@@ -20,7 +20,7 @@ def dipole_field(
     field: str, default=`'B'`
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
         in units of [kA/m].
 

diff --git a/magpylib/_src/fields/field_BH_line.py b/magpylib/_src/fields/field_BH_line.py
@@ -9,7 +9,7 @@
 
 def current_vertices_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     current: np.ndarray,
     vertices: list=None,
     segment_start=None,  # list of mix3 ndarrays
@@ -30,10 +30,10 @@ def current_vertices_field(
     - B-field (ndarray nx3): B-field vectors at pos_obs in units of mT
     """
     if vertices is None:
-        return current_line_field(field, observer, current, segment_start, segment_end)
+        return current_line_field(field, observers, current, segment_start, segment_end)
 
     nv = len(vertices)           # number of input vertex_sets
-    npp = int(observer.shape[0]/nv)  # number of position vectors
+    npp = int(observers.shape[0]/nv)  # number of position vectors
     nvs = [len(vset)-1 for vset in vertices] # length of vertex sets
     nseg = sum(nvs)                             # number of segments
 
@@ -43,16 +43,16 @@ def current_vertices_field(
     pos_end = np.concatenate([vert[1:] for vert in vertices])
 
     # create input for vectorized computation in one go
-    observer = np.reshape(observer, (nv, npp,3))
-    observer = np.repeat(observer, nvs, axis=0)
-    observer = np.reshape(observer, (-1, 3))
+    observers = np.reshape(observers, (nv, npp,3))
+    observers = np.repeat(observers, nvs, axis=0)
+    observers = np.reshape(observers, (-1, 3))
 
     curr_tile = np.repeat(curr_tile, npp)
     pos_start = np.repeat(pos_start, npp, axis=0)
     pos_end = np.repeat(pos_end, npp, axis=0)
 
     # compute field
-    field = current_line_field(field, observer, curr_tile, pos_start, pos_end)
+    field = current_line_field(field, observers, curr_tile, pos_start, pos_end)
     field = np.reshape(field, (nseg, npp, 3))
 
     # sum for each vertex set
@@ -65,7 +65,7 @@ def current_vertices_field(
 # ON INTERFACE
 def current_line_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     current: np.ndarray,
     segment_start: np.ndarray,
     segment_end: np.ndarray,
@@ -81,7 +81,7 @@ def current_line_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     current: ndarray, shape (n,)
@@ -138,10 +138,10 @@ def current_line_field(
         current = current[not_mask0]
         segment_start = segment_start[not_mask0]
         segment_end = segment_end[not_mask0]
-        observer = observer[not_mask0]
+        observers = observers[not_mask0]
 
     # rename
-    p1,p2,po = segment_start, segment_end, observer
+    p1,p2,po = segment_start, segment_end, observers
 
     # make dimensionless (avoid all large/small input problems) by introducing
     # the segment length as characteristic length scale.

diff --git a/magpylib/_src/fields/field_BH_loop.py b/magpylib/_src/fields/field_BH_loop.py
@@ -13,7 +13,7 @@
 # ON INTERFACE
 def current_loop_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     current: np.ndarray,
     diameter: np.ndarray,
     ) -> np.ndarray:
@@ -27,7 +27,7 @@ def current_loop_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     current: ndarray, shape (n,)

diff --git a/magpylib/_src/fields/field_BH_sphere.py b/magpylib/_src/fields/field_BH_sphere.py
@@ -9,7 +9,7 @@
 
 def magnet_sphere_field(
     field: str,
-    observer: np.ndarray,
+    observers: np.ndarray,
     magnetization: np.ndarray,
     diameter: np.ndarray,
     )->np.ndarray:
@@ -23,7 +23,7 @@ def magnet_sphere_field(
         If `field='B'` return B-field in units of [mT], if `field='H'` return H-field
         in units of [kA/m].
 
-    observer: ndarray, shape (n,3)
+    observers: ndarray, shape (n,3)
         Observer positions (x,y,z) in Cartesian coordinates in units of [mm].
 
     magnetization: ndarray, shape (n,3)

diff --git a/magpylib/_src/fields/field_wrap_BH_level1.py b/magpylib/_src/fields/field_wrap_BH_level1.py
@@ -24,7 +24,7 @@ def getBH_level1(
     source_type: str,
     position: np.ndarray,
     orientation: np.ndarray,
-    observer: np.ndarray,
+    observers: np.ndarray,
     **kwargs: dict,
 ) -> np.ndarray:
     """Vectorized field computation
@@ -45,19 +45,15 @@ def getBH_level1(
     # pylint: disable=too-many-branches
 
     # transform obs_pos into source CS
-    pos_rel_rot = orientation.apply(observer - position, inverse=True)
+    pos_rel_rot = orientation.apply(observers - position, inverse=True)
 
     # collect dictionary inputs and compute field
     field_func = FIELD_FUNCTIONS.get(source_type, None)
 
-    if source_type == 'CustomSource':
+    if source_type == "CustomSource":
         field = kwargs["field"]
-        if kwargs.get('field_func', None) is not None:
-            BH = kwargs['field_func'](field, pos_rel_rot)
-        else:
-            raise MagpylibInternalError(
-                'No field calculation not provided for CustomSource class'
-            )
+        if kwargs.get("field_func", None) is not None:
+            BH = kwargs["field_func"](field, pos_rel_rot)
     elif field_func is not None:
         BH = field_func(observer=pos_rel_rot, **kwargs)
     else:

diff --git a/magpylib/_src/fields/field_wrap_BH_level2.py b/magpylib/_src/fields/field_wrap_BH_level2.py
@@ -128,7 +128,7 @@ def getBH_level2(
     if isinstance(sources, str):
         return getBH_dict_level2(
             source_type=sources,
-            observer=observers,
+            observers=observers,
             field=field,
             squeeze=squeeze,
             **kwargs,

diff --git a/magpylib/_src/fields/field_wrap_BH_level2_dict.py b/magpylib/_src/fields/field_wrap_BH_level2_dict.py
@@ -8,7 +8,7 @@
 
 
 PARAM_TILE_DIMS = {
-    "observer": 2,
+    "observers": 2,
     "position": 2,
     "orientation": 2,
     "magnetization": 2,
@@ -23,15 +23,15 @@
 
 def getBH_dict_level2(
     source_type,
-    observer,
+    observers,
     *,
     field: str,
     position=(0, 0, 0),
     orientation=R.identity(),
     squeeze=True,
     **kwargs: dict,
 ) -> np.ndarray:
-    """ Direct interface access to vectorized computation
+    """Direct interface access to vectorized computation
 
     Parameters
     ----------
@@ -66,7 +66,7 @@ def getBH_dict_level2(
             " when using the direct interface."
         )
 
-    kwargs["observer"] = observer
+    kwargs["observers"] = observers
     kwargs["position"] = position
 
     # change orientation to Rotation numpy array for tiling
@@ -79,8 +79,7 @@ def getBH_dict_level2(
             val = np.array(val, dtype=float)
         except TypeError as err:
             raise MagpylibBadUserInput(
-                f"{key} input must be array-like.\n"
-                f"Instead received {val}"
+                f"{key} input must be array-like.\n" f"Instead received {val}"
             ) from err
         tdim = PARAM_TILE_DIMS.get(key, 1)
         if val.ndim == tdim:

diff --git a/magpylib/_src/input_checks.py b/magpylib/_src/input_checks.py
@@ -133,33 +133,22 @@ def validate_field_func(val):
     - needs to be a callable
     - input and output shape must match
     """
-    if val is not None:
-        msg = ""
-        if not callable(val):
-            msg = f"Instead received {type(val).__name__}."
-        else:
-            fn_args = inspect.getfullargspec(val).args
-            if fn_args[:2] != ["field", "observer"]:
-                msg = f"Instead received a callable, the first two args being: {fn_args[:2]}"
-            else:
-                out = val("B", np.array([[1, 2, 3], [4, 5, 6]]))
-                out_shape = np.array(out).shape
-                if out_shape != (2, 3):
-                    msg = (
-                        "Function test call with observer of shape (2,3) failed, "
-                        f"instead received shape {out_shape}."
-                    )
-
-        if msg:
-            raise MagpylibBadUserInput(
-                "Input parameter `field_func` must be a callable "
-                "accepting the two positional arguments `field` and `observer` "
-                "(e.g. `def myfieldfunc(field, observer, ...): ...`. The `field` argument must "
-                "accept one of ('B','H') and the `observer` an ndarray of shape (n,3). "
-                "The returned field must be an ndarray matching the observer shape.\n"
-                + msg
-            )
-    return val
+    if val is None:
+        return None
+
+    if not callable(val):
+        raise MagpylibBadUserInput(
+            "Input parameter `field_func` must be a callable.\n"
+            f"Instead received {type(val).__name__}."
+        )
+
+    fn_args = inspect.getfullargspec(val).args
+    if fn_args[:2] != ["field", "observers"]:
+        raise MagpylibBadUserInput(
+            "Input parameter `field_func` must have two positional args"
+            " called 'field' and 'observers'.\n"
+            f"Instead received a callable where the first two args are: {fn_args[:2]}"
+        )
 
     for field in ['B', 'H']:
         out = val(field, np.array([[1, 2, 3], [4, 5, 6]]))