V4 docstrings (#479)

* new input checks with properly formatted error messages

* checkinputs parameter is completely out, input checks are always performed

* not more tool tip codes dimension=(a,b,c) but only dimension=None inits

* complete docstings of V4 codes

* some minor code refactorings and mini-bugfixes

Co-authored-by: Boisselet Alexandre (IFAT DC ATV SC D TE2) <Alexandre.Boisselet@infineon.com>
Co-authored-by: Alexandre Boisselet <alexabois@gmail.com>

magpylib/__init__.py

@@ -126,7 +126,7 @@
 
 # module level dunders
 __version__ = '4.0.0'
-__author__ =  'Michael Ortner & Alexandre Boissolet'
+__author__ =  'Michael Ortner & Alexandre Boisselet'
 __credits__ = 'The Magpylib community'
 __all__ = ['magnet', 'current', 'misc', 'getB', 'getH',
     'Sensor', 'Collection', 'show', 'defaults', '__version__',

magpylib/_src/defaults/defaults_classes.py

@@ -8,33 +8,21 @@
 from magpylib._src.style import DisplayStyle
 
 
-# ON INTERFACE
 class DefaultConfig(MagicProperties):
     """Library default settings.
 
     Parameters
     ----------
-    checkinputs: bool, default=True
-        Check user input types, shapes at various stages and raise errors
-        when they are not within designated parameters.
-
-
     display: dict or Display
         `Display` class containing display settings. `('backend', 'animation', 'colorsequence' ...)`
     """
 
     def __init__(
         self,
-        checkinputs=None,
-        edgesize=None,
-        itercylinder=None,
         display=None,
         **kwargs,
     ):
         super().__init__(
-            checkinputs=checkinputs,
-            edgesize=edgesize,
-            itercylinder=itercylinder,
             display=display,
             **kwargs,
         )
@@ -45,50 +33,6 @@ def reset(self):
         self.update(get_defaults_dict(), _match_properties=False)
         return self
 
-    @property
-    def checkinputs(self):
-        """Check user input types, shapes at various stages and raise errors
-        when they are not within designated parameters."""
-        return self._checkinputs
-
-    @checkinputs.setter
-    def checkinputs(self, val):
-        assert val is None or isinstance(val, bool), (
-            f"the `checkinputs` property of {type(self).__name__} must be either `True` or `False`"
-            f" but received {repr(val)} instead"
-        )
-        self._checkinputs = val
-
-    @property
-    def edgesize(self):
-        """getB and getH return 0 on edge, formulas often show singularities there and undefined
-        forms. EDGESIZE defines how close to the edge 0 will be returned to avoid running into
-        numerical instabilities."""
-        return self._edgesize
-
-    @edgesize.setter
-    def edgesize(self, val):
-        assert val is None or isinstance(val, (int, float)) and val > 0, (
-            f"the `edgesize` property of {type(self).__name__} must be a strictly positive number"
-            f" but received {repr(val)} instead"
-        )
-        self._edgesize = val
-
-    @property
-    def itercylinder(self):
-        """Cylinder with diametral magnetization uses Simpsons iterative formula
-        to compute the integral. More iterations increase precision but slow
-        down the computation."""
-        return self._itercylinder
-
-    @itercylinder.setter
-    def itercylinder(self, val):
-        assert val is None or isinstance(val, int) and val > 0, (
-            f"the `itercylinder` property of {type(self).__name__} must be a strictly positive"
-            f" integer but received {repr(val)} instead"
-        )
-        self._itercylinder = val
-
     @property
     def display(self):
         """`Display` class containing display settings.

magpylib/_src/defaults/defaults_values.py

@@ -1,7 +1,6 @@
 """Package level config defaults"""
 
 DEFAULTS = {
-    "checkinputs": True,
     "display": {
         "autosizefactor": 10,
         "animation": {

magpylib/_src/display/display.py

@@ -3,12 +3,16 @@
 import warnings
 from magpylib._src.utility import format_obj_input, test_path_format
 from magpylib._src.display.display_matplotlib import display_matplotlib
-from magpylib._src.input_checks import check_dimensions
-from magpylib._src.defaults.defaults_classes import default_settings as Config
-from magpylib._src.exceptions import MagpylibBadUserInput
-from magpylib._src.defaults.defaults_utility import SUPPORTED_PLOTTING_BACKENDS
+from magpylib._src.input_checks import (
+    check_dimensions,
+    check_excitations,
+    check_format_input_backend,
+    check_input_zoom,
+    check_input_animation,
+    check_format_input_vector,
+    )
+
 
-# ON INTERFACE
 def show(
     *objects,
     zoom=0,
@@ -18,39 +22,41 @@ def show(
     canvas=None,
     **kwargs,
 ):
-    """
-    Display objects and paths graphically. Style input can be a style-dict or
+    """Display objects and paths graphically.
+
+    Global graphic styles can be set with kwargs as style-dictionary or using
     style-underscore_magic.
 
     Parameters
     ----------
-    objects: sources, collections or sensors
+    objects: Magpylib objects (sources, collections, sensors)
         Objects to be displayed.
 
-    zoom: float, default = 0
+    zoom: float, default=`0`
         Adjust plot zoom-level. When zoom=0 3D-figure boundaries are tight.
 
-    animation: bool, default=False
-        If True and at least one object has a path, animated paths are rendered.
-        If a positive float, the animation duration target is set to the given value.
-        This feature is only available for the `plotly` backend at the moment.
+    animation: bool or float, default=`False`
+        If `True` and at least one object has a path, the paths are rendered.
+        If input is a positive float, the animation time is set to the given value.
+        This feature is only available for the plotly backend.
 
-    markers: array_like, shape (N,3), default=None
-        Display position markers in the global CS. By default no marker is displayed.
+    markers: array_like, shape (n,3), default=`None`
+        Display position markers in the global coordinate system.
 
-    backend: string, default=None
-        One of `'matplotlib'` or `'plotly'`. If not set, parameter will default to
-        magpylib.defaults.display.backend which comes as 'matplotlib' with installation.
+    backend: string, default=`None`
+        Define plotting backend. Must be one of `'matplotlib'` or `'plotly'`. If not
+        set, parameter will default to `magpylib.defaults.display.backend` which is
+        `'matplotlib'` by installation default.
 
-    canvas: pyplot Axis or plotly Figure, default=None
-        Display graphical output in a given canvas:
-        - with matplotlib: pyplot axis (must be 3D).
-        - with plotly: plotly.graph_objects.Figure or plotly.graph_objects.FigureWidget
-        By default a new canvas is created and displayed.
+    canvas: matplotlib.pyplot `AxesSubplot` or plotly `Figure` object, default=`None`
+        Display graphical output on a given canvas:
+        - with matplotlib: `matplotlib.axes._subplots.AxesSubplot` with `projection=3d.
+        - with plotly: `plotly.graph_objects.Figure` or `plotly.graph_objects.FigureWidget`.
+        By default a new canvas is created and immediately displayed.
 
     Returns
     -------
-    None: NoneType
+    `None`: NoneType
 
     Examples
     --------
@@ -59,15 +65,15 @@ def show(
 
     >>> import magpylib as magpy
     >>> src = magpy.magnet.Sphere(magnetization=(0,0,1), diameter=1)
-    >>> src.move([(.1,0,0)]*50, increment=True)
-    >>> src.rotate_from_angax(angle=[10]*50, axis='z', anchor=0, start=0, increment=True)
+    >>> src.move([(0.1*x,0,0) for x in range(50)])
+    >>> src.rotate_from_angax(angle=range(0,400,10), axis='z', anchor=0, start=11)
     >>> ts = [-.4,0,.4]
     >>> sens = magpy.Sensor(position=(0,0,2), pixel=[(x,y,0) for x in ts for y in ts])
     >>> magpy.show(src, sens)
     >>> magpy.show(src, sens, backend='plotly')
     --> graphic output
 
-    Display figure on your own canvas (here Matplotlib 3D axis):
+    Display output on your own canvas (here a Matplotlib 3d-axes):
 
     >>> import matplotlib.pyplot as plt
     >>> import magpylib as magpy
@@ -82,11 +88,11 @@ def show(
     or as global style arguments in display.
 
     >>> import magpylib as magpy
-    >>> src1 = magpy.magnet.Sphere((1,1,1), 1)
-    >>> src2 = magpy.magnet.Sphere((1,1,1), 1, (1,0,0))
+    >>> src1 = magpy.magnet.Sphere((1,1,1), 1, [(0,0,0), (0,0,3)])
+    >>> src2 = magpy.magnet.Sphere((1,1,1), 1, [(1,0,0), (1,0,3)], style_path_show=False)
     >>> magpy.defaults.display.style.magnet.magnetization.size = 2
     >>> src1.style.magnetization.size = 1
-    >>> magpy.show(src1, src2, style_color='r', zoom=3)
+    >>> magpy.show(src1, src2, style_color='r')
     --> graphic output
     """
 
@@ -96,17 +102,27 @@ def show(
 
     # test if all source dimensions and excitations have been initialized
     check_dimensions(obj_list_flat)
+    check_excitations(obj_list_flat)
 
     # test if every individual obj_path is good
     test_path_format(obj_list_flat)
 
-    if backend is None:
-        backend = Config.display.backend
+    # input checks
+    backend = check_format_input_backend(backend)
+    check_input_zoom(zoom)
+    check_input_animation(animation)
+    check_format_input_vector(
+        markers,
+        dims=(2,),
+        shape_m1=3,
+        sig_name='markers',
+        sig_type='array_like of shape (n,3)',
+        allow_None=True)
 
     if backend == "matplotlib":
         if animation is not False:
-            msg = "The matplotlib backend does not support animation at the moment. "
-            msg += "Use plotly backend instead."
+            msg = "The matplotlib backend does not support animation at the moment.\n"
+            msg+= "Use `backend=plotly` instead."
             warnings.warn(msg)
             # animation = False
         display_matplotlib(
@@ -124,9 +140,3 @@ def show(
             animation=animation,
             **kwargs,
         )
-    else:
-        msg = (
-            f"The plotting backend must be one of {SUPPORTED_PLOTTING_BACKENDS},"
-            f" received {backend!r} instead"
-        )
-        raise MagpylibBadUserInput(msg)