Merge pull request #218 from magpylib/development

Development

CHANGELOG.md

@@ -12,6 +12,13 @@ Click here for [Unreleased Changes]
 
 # Releases
 
+## [1.2.1b0] - 2019-07-31
+### Changed
+- Optimized getB call (utility integrated)
+- Improved Documentation (added Sensor class v1)
+
+---
+
 ## [1.2.0b0] - 2019-07-16
 ### Added
 - Sensor Class
@@ -113,6 +120,7 @@ The first official release of the magpylib library.
 ---
 
 [Unreleased Changes]: https://github.com/magpylib/magpylib/compare/HEAD...development
+[1.2.1b0]: https://github.com/magpylib/magpylib/compare/1.2.0-beta...1.2.1-beta
 [1.2.0b0]: https://github.com/magpylib/magpylib/compare/1.1.1-beta...1.2.0-beta
 [1.1.1b0]: https://github.com/magpylib/magpylib/compare/1.1.0-beta...1.1.1-beta
 [1.1.0b0]: https://github.com/magpylib/magpylib/compare/1.0.1-beta...1.1.0-beta

docs/_pages/0_documentation.md

@@ -8,6 +8,7 @@ The idea behind magpylib is to provide simple and easy to use classes for calcul
 In this part of the documentation the fundamental structure of the magpylib library is detailed.
 
 - Content
+- [Library Documentation](#library-documentation)
   - [Package Structure](#package-structure)
   - [Units and IO Types](#units-and-io-types)
   - [The Source Class](#the-source-class)
@@ -22,6 +23,7 @@ In this part of the documentation the fundamental structure of the magpylib libr
       - [Complex Magnet Geometries](#complex-magnet-geometries)
       - [Display Collection Graphically](#display-collection-graphically)
   - [Math Package](#math-package)
+  - [The Sensor Class](#the-sensor-class)
 
 
 ## Package Structure
@@ -396,3 +398,26 @@ The math package provides some functions for easier use of the angle-axis (Quate
   positionNew = magpy.math.rotatePosition(pos0,angle,axis,anchor)
   print(positionNew)                  #Output = [2. 0. 0.]
   ```
+
+
+## The Sensor Class
+
+```eval_rst
+The field sampling method, getB, in the :class:`magpylib.source` classes will always extract the field components from an absolute orientation in the coordinate space, given a position. 3D sensors do not behave in this manner as their readings are affected the most by their positioning and tilt relative to the system they are sensing. 
+
+Since version 1.2-beta, magpylib now offers the :class:`magpylib.Sensor` class, which provides an object that may be placed and oriented in a coordinate space. This allows for quick analysis of relative measurements of system arrangements. Here is an example:
+
+.. plot:: pyplots/doku/sensorSource.py
+   :include-source:
+
+```
+
+
+```eval_rst
+
+The sensors may also read multiple sources in a :class:`magpylib.Collection`, and be displayed using the :meth:`magpylib.Collection.displaySystem()` method by using the sensors keyword argument. Multiple sensors may be displayed.
+
+.. plot:: pyplots/doku/thorsHammerSensor.py
+   :include-source:
+
+```

docs/conf.py

@@ -68,7 +68,7 @@ def setup(app):
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '1.2.0-beta'
+release = '1.2.1-beta'
 
 
 # -- General configuration ---------------------------------------------------

docs/pyplots/doku/sensorSource.py

@@ -0,0 +1,21 @@
+from magpylib import source, Sensor, Collection
+
+
+##### Single source example
+sensorPosition = [5,0,0]
+sensor = Sensor(pos=sensorPosition,
+                angle=90,
+                axis=(0,0,1))
+
+cyl = source.magnet.Cylinder([1,2,300],[0.2,1.5])
+
+# Read field from absolute position in system
+absoluteReading = cyl.getB(sensorPosition)
+print(absoluteReading)
+# [ 0.50438605   1.0087721  297.3683702 ]
+
+# Now, read from sensor and print the relative output
+relativeReading = sensor.getB(cyl)
+print(relativeReading)
+# [ 1.0087721   -0.50438605 297.3683702 ]
+

docs/pyplots/doku/thorsHammerSensor.py

@@ -0,0 +1,35 @@
+from magpylib import source, Sensor, Collection
+from numpy import around
+##### Define Sensors
+sensor0Position = [2,1,-2]
+sensor1Position = [-2,-1,-2]
+sensor0 = Sensor(pos=sensor0Position,
+                angle=90,
+                axis=(0,0,1))
+sensor1 = Sensor(sensor1Position,0,(0,0,1))
+
+##### Define magnets, Collection system
+cyl = source.magnet.Cylinder([1,2,300],[0.2,1.5])
+box = source.magnet.Box([1,2,300],[1,1,0.5],[0,0,1])
+col = Collection(cyl,box)
+
+# Read from absolute position in Collection system
+absoluteReading = [col.getB(sensor0Position), col.getB(sensor1Position)]
+print(absoluteReading)
+# [ array([-0.34285586, -0.17269852,  0.22153783]), 
+#   array([0.34439442, 0.1707909 , 0.22611859])]
+
+# Rotated sensor reading
+relativeReading = [sensor0.getB(col),sensor1.getB(col)]
+print(relativeReading)
+# [ array([-0.17269852,  0.34285586,  0.22153783]), 
+#   array([0.34439442, 0.1707909 , 0.22611859])]
+
+sensorList = [sensor0, sensor1]
+markerText0 = "sensor0:{}".format(around(relativeReading[0],2))
+markerText1 = "sensor1:{}".format(around(relativeReading[1],2))
+markerList = [ sensor0Position + [markerText0],
+               sensor1Position + [markerText1],
+               [3,3,3]]
+
+col.displaySystem(sensors=sensorList , markers=markerList, direc=True)

magpylib/_lib/classes/currents.py

@@ -36,7 +36,7 @@
 
 # %% IMPORTS
 from numpy import array, float64, ndarray
-from magpylib._lib.utility import getBField, rotateToCS
+from magpylib._lib.mathLibPrivate import angleAxisRotation
 from magpylib._lib.fields.Current_Line import Bfield_CurrentLine
 from magpylib._lib.fields.Current_CircularLoop import Bfield_CircularCurrentLoop
 from magpylib._lib.classes.base import LineCurrent
@@ -111,9 +111,17 @@ def __init__(self, curr=I, dim=d, pos=(0.0, 0.0, 0.0), angle=0.0, axis=(0.0, 0.0
         self.dimension = float(dim)
 
     def getB(self, pos):  # Particular Circular current B field calculation. Check RCS for getB() interface
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_CircularCurrentLoop(self.current, self.dimension, rotatedPos),  # The B field
-                         self)
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_CircularCurrentLoop(self.current,self.dimension,rotatedPos))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
 
     def __repr__(self):
         """
@@ -218,9 +226,17 @@ def __init__(self, curr=I, vertices=listOfPos, pos=(0.0, 0.0, 0.0), angle=0.0, a
         self.vertices = array(vertices, dtype=float64, copy=False)
 
     def getB(self, pos):  # Particular Line current B field calculation. Check RCS for getB() interface
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_CurrentLine(rotatedPos, self.vertices, self.current),  # The B field
-                         self)
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_CurrentLine(rotatedPos, self.vertices, self.current))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
 
     def __repr__(self):
         """

magpylib/_lib/classes/magnets.py

@@ -30,7 +30,9 @@
 #######################################
 
 # %% IMPORTS
-from magpylib._lib.utility import checkDimensions, getBField, rotateToCS
+from numpy import array, float64, ndarray
+from magpylib._lib.mathLibPrivate import angleAxisRotation
+from magpylib._lib.utility import checkDimensions
 from magpylib._lib.classes.base import HomoMag
 from magpylib._lib.fields.PM_Sphere import Bfield_Sphere
 from magpylib._lib.fields.PM_Cylinder import Bfield_Cylinder
@@ -99,19 +101,25 @@ class Box(HomoMag):
     """
 
     def __init__(self, mag=(Mx, My, Mz), dim=(a, b, c), pos=(0.0, 0.0, 0.0), angle=0.0, axis=(0.0, 0.0, 1.0)):
-
         # inherit class HomoMag
         HomoMag.__init__(self, pos, angle, axis, mag)
 
         # secure input type and check input format of dim
         self.dimension = checkDimensions(3, dim, "Bad dim for box")
 
-    # Private method. This is used by getB for multiprocess reference.
     def getB(self, pos):
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_Box(self.magnetization, rotatedPos, self.dimension),  # The B field
-                         self)  # Object Angle/Axis properties
-
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_Box(self.magnetization, rotatedPos, self.dimension))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
+
     def __repr__(self):
         """
         This is for the IPython Console
@@ -218,9 +226,17 @@ def __init__(self, mag=(Mx, My, Mz), dim=(d, h), pos=(0.0, 0.0, 0.0), angle=0.0,
         self.iterDia = iterDia
 
     def getB(self, pos):  # Particular Cylinder B field calculation. Check RCS for getB() interface
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_Cylinder(self.magnetization, rotatedPos, self.dimension, self.iterDia),  # The B field
-                         self)  # Object Angle/Axis properties
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_Cylinder(self.magnetization, rotatedPos, self.dimension, self.iterDia))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
 
     def __repr__(self):
         """
@@ -313,9 +329,17 @@ def __init__(self, mag=(Mx, My, Mz), dim=d, pos=(0.0, 0.0, 0.0), angle=0.0, axis
         assert self.dimension > 0, 'Bad dim<=0 for sphere'
 
     def getB(self, pos):
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_Sphere(self.magnetization, rotatedPos, self.dimension),  # The B Field
-                         self)  # Object Angle/Axis properties
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_Sphere(self.magnetization, rotatedPos, self.dimension))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
 
     def __repr__(self):
         """

magpylib/_lib/classes/moments.py

@@ -28,7 +28,8 @@
 #######################################
 
 # %% IMPORTS
-from magpylib._lib.utility import getBField, rotateToCS
+from numpy import array, float64, ndarray
+from magpylib._lib.mathLibPrivate import angleAxisRotation
 from magpylib._lib.classes.base import MagMoment
 from magpylib._lib.fields.Moment_Dipole import Bfield_Dipole
 
@@ -87,9 +88,17 @@ class Dipole(MagMoment):
     """
 
     def getB(self, pos):  # Particular Line current B field calculation. Check RCS for getB() interface
-        rotatedPos = rotateToCS(pos, self)
-        return getBField(Bfield_Dipole(self.moment, rotatedPos),  # The B field
-                         self)  # Object Angle/Axis properties
+        # secure input type and check input format
+        p1 = array(pos, dtype=float64, copy=False)
+        # relative position between mag and obs
+        posRel = p1 - self.position
+        # rotate this vector into the CS of the magnet (inverse rotation)
+        rotatedPos = angleAxisRotation(self.angle, -self.axis, posRel) # pylint: disable=invalid-unary-operand-type
+        # rotate field vector back
+        BCm = angleAxisRotation(self.angle, self.axis, Bfield_Dipole(self.moment, rotatedPos))
+        # BCm is the obtained magnetic field in Cm
+        # the field is well known in the magnet coordinates.
+        return BCm
 
     def __repr__(self):
         """

magpylib/_lib/utility.py

@@ -258,32 +258,6 @@ def drawDipole(position, moment, angle, axis, SYSSIZE, ax):
 
 # Source package helpers
 
-def rotateToCS(pos, source_ref):
-        # Used in all getB()
-    from magpylib._lib.mathLibPrivate import angleAxisRotation
-    # secure input type and check input format
-    p1 = array(pos, dtype=float64, copy=False)
-
-    # relative position between mag and obs
-    posRel = p1 - source_ref.position
-
-    # rotate this vector into the CS of the magnet (inverse rotation)
-    # Leave this alone for now pylint: disable=invalid-unary-operand-type
-    p21newCm = angleAxisRotation(source_ref.angle, -source_ref.axis, posRel)
-
-    return p21newCm
-
-
-def getBField(BCm, source_ref):
-    # Used in all getB()
-    # BCm is the obtained magnetic field in Cm
-    # the field is well known in the magnet coordinates
-    from magpylib._lib.mathLibPrivate import angleAxisRotation
-    # rotate field vector back
-    B = angleAxisRotation(source_ref.angle, source_ref.axis, BCm)
-
-    return B
-
 
 def recoordinateAndGetB(source_ref, args):
     ## Used in base.RCS.getBDisplacement(),

setup.py

@@ -16,7 +16,7 @@
 #   $ (packCondaTest) pip install .
 # The library is now in the packCondaTest environment.
 ##
-_magPyVersion = "1.2.0-beta"
+_magPyVersion = "1.2.1-beta"
 
 _SphinxVersion = "1.8.2"
 _name = "magpylib"