doku fix all examples and references

Author: OrtnerMichael

docs/_pages/0_documentation.rst

@@ -416,6 +416,7 @@ Then top level function ``displaySystem(c)`` can be used to quickly check the ge
 * ``suppress=True`` for suppressing the immediate figure output when the function is called. To do so it is necessary to deactivate the interactive mode by calling ``pyplot.ioff()``. With `Spyder's <https://www.spyder-ide.org/>`_ IPython *Inline* plotting, graphs made with :meth:`~magpylib.displaySystem()` can be blank if the ``suppress=True`` option is not used. Set IPython Graphics backend to *Automatic* or *Qt5* instead of *Inline* in settings/IPython console/Graphics method to address this.
 * ``direc=True`` for displaying current and magnetization directions in the figure.
 * ``subplotAx=None`` for displaying the plot on a designated figure subplot instance.
+* ``figsize=(8,8)`` for setting the size of the output graphic.
 
 The following example code shows how to use ``displaySystem()``:
 

docs/_pages/2_guideExamples.rst

@@ -4,7 +4,19 @@
 Example Codes
 *******************************
 
-This section includes a few code examples that show how the library can be used. Detailed information about the library structure can be found in the :ref:`docu`.
+This section includes a few code examples that show how the library can be used and what i can be used for. A detailed technical library documentation can be found in the :ref:`docu`.
+
+
+Contents
+########
+
+* :ref:`examples-simplest`
+* :ref:`examples-basic`
+* :ref:`examples-sourceObjects`
+* :ref:`examples-motionBasics`
+* :ref:`examples-joystick`
+* :ref:`examples-complexShapes`
+* :ref:`examples-vector`
 
 
 
@@ -30,7 +42,7 @@ The simplest possible example - calculate the B-field of a cylinder with 3 lines
 Basic Functionality: The Field of a Collection
 ###############################################
 
-In this example the basic functionality is outlined by calculating the field of two magnets. The magnets are geometrically manipulated and the system geometry is displayed using the `displaySystem` method. The field is then calculated on a grid and displayed in the xz-plane.
+In this example the basic functionality is outlined. Two magnet objects are created and geometrically manipulated. The system geometry is then displayed using the ``displaySystem`` function. Finally, the field is calculated on a grid and displayed in the xz-plane.
 
 .. plot:: pyplots/examples/01_SimpleCollection.py
     :include-source:
@@ -44,7 +56,7 @@ In this example the basic functionality is outlined by calculating the field of
 The Source Objects and their Fields
 ###################################
 
-In this example we define all existing source objects and display their fields. Notice that the respective magnetization vectors are chosen arbitrarily.
+In this example we define all currently implemented source objects and display their fields. Notice that the respective magnetization vectors are chosen arbitrarily.
 
 .. plot:: pyplots/examples/01b_AllSources.py
    :include-source:
@@ -58,34 +70,38 @@ In this example we define all existing source objects and display their fields.
 Translation, Orientation and Rotation Basics
 #############################################
 
-Translation of magnets can be realized in three ways, using the methods `move` and `setPosition`, or by directly setting the object `position` attribute.
+Translation of magnets can be realized in three ways, using the methods ``move`` and ``setPosition``, or by directly setting the object ``position`` attribute.
 
 .. plot:: pyplots/examples/00a_Trans.py
    :include-source:
 
 :download:`00a_Trans.py <../pyplots/examples/00a_Trans.py>`
 
-The next example shows a cubical magnet initialized with four different orientations defined by the classical Euler angle rotations about the three Cartesian axes. Notice that the magnetization direction is defined in the INIT ORIENTATION so that different orientations results in a rotation of the magnetization vector.
+
+Initialize magnets with different orientations defined by classical Euler angle rotations about the three Cartesian axes. Notice that the magnetization direction is fixed with respect to the **init orientation** of the magnet and will rotate together with the magnet.
 
 .. plot:: pyplots/examples/00b_OrientRot1.py
    :include-source:
 
 :download:`00b_OrientRot1.py <../pyplots/examples/00b_OrientRot1.py>`
 
-The following example shows a general form of orientation for different angles about an axis (1,-1,1). The upper three boxes are initialized with different orientations. The lower three boxes are all initialized with INIT ORIENTATION and are then rotated (about themselves) to achieve the same result as above.
+
+The following example shows functionality beyond Euler angle rotation. This means rotation about an arbitrary axis of choice, here ``(1,-1,1)``. The upper three boxes are initialized with different orientations. The lower three boxes are all initialized with **init orientation** and are then rotated (about themselves) to achieve the same result as above.
 
 .. plot:: pyplots/examples/00c_OrientRot2.py
    :include-source:
 
 :download:`00c_OrientRot2.py <../pyplots/examples/00c_OrientRot2.py>`
 
-The following example shows rotations with designated anchor-axis combinations. Here we distinguish between pivot points (the closest point on the rotation axis to the magnet) and anchor points which are simply required to define an axis in 3D space (together with the direction).
+
+The following example shows rotations with designated anchor-axis combinations. Here we distinguish between pivot points (the closest point on the rotation axis to the magnet) and anchor points which are simply required to define an axis in 3D space (together with a direction).
 
 .. plot:: pyplots/examples/00d_OrientRot3.py
    :include-source:
 
 :download:`00d_OrientRot3.py <../pyplots/examples/00d_OrientRot3.py>`
 
+
 Collections can be manipulated using the previous logic as well. Notice how objects can be grouped into collections and sub-collections for common manipulation. For rotations keep in mind that if an anchor is not provided, all objects will rotate relative to their own center.
 
 .. plot:: pyplots/examples/00e_ColTransRot.py
@@ -100,9 +116,9 @@ Collections can be manipulated using the previous logic as well. Notice how obje
 Magnet Motion: Simulating a Magnetic Joystick
 ##############################################
 
-In this example a joystick is simulated. A magnetic joystick is realized by a rod that can tilt freely (two degrees of freedom) about a center of tilt. The upper part of the rod is the joystick handle. At the bottom of the rod a cylindrical magnet (dimension *D/H*) with axial magnetization (amplitude *M0*) is fixed. The magnet lies at a distance *d* below the center of tilt. The system is constructed such that, when the joystick is in the center position a sensor lies at distance *gap* below the magnet and in the origin of a Cartesian coordinate system. The magnet thus moves with the joystick above the fixed sensor.
+In this example a joystick is simulated. A magnetic joystick is realized by a rod that can tilt freely (two degrees of freedom) about a center of tilt. The upper part of the rod is the joystick handle. At the bottom of the rod a cylindrical magnet (``dim=(D,H)``) with axial magnetization ```mag=[0,0,M0]`` is fixed. The magnet lies at a distance ``d`` below the center of tilt. The system is constructed such that, when the joystick is in the center position a sensor lies at distance ``gap`` below the magnet and in the origin of a Cartesian coordinate system. The magnet thus moves with the joystick above the fixed sensor.
 
-In the following program the magnetic field is calculated for all degrees of freedom. Different tilt angles are set by rotation about the center of tilt by the angle *th* (different colors). Then the tilt direction is varied from 0 to 360 degrees by simulating the magnet 'motion' as rotation about the z-axis, see also the following sketch.
+In the following program the magnetic field is calculated for all degrees of freedom. Different tilt angles are set by rotation about the center of tilt by the angle ``th`` (different colors). Then the tilt direction is varied from 0 to 360 degrees by simulating the magnet motion as rotation about the z-axis, see also the following sketch.
 
 .. image:: ../_static/images/examples/JoystickExample1.JPG
    :align: center
@@ -120,7 +136,7 @@ In the following program the magnetic field is calculated for all degrees of fre
 Complex Magnet Shapes: Hollow Cylinder
 ###########################################
 
-The superposition principle allows us to calculate complex magnet shapes by 'addition' and 'subtraction' operations. A common application for this is the field of an axially magnetized hollow cylinder. The hollow part is cut out of the first cylinder by placing a second, smaller cylinder inside with opposite magnetization. Unfortunately the `displaySystem` method cannot properly display such objects intersecting with each other.
+The superposition principle allows us to calculate complex magnet shapes by *addition* and *subtraction* operations. An example application for this is the field of an axially magnetized hollow cylinder. The hollow part is cut out from the outer cylinder by placing a second, smaller cylinder inside with opposite magnetization. Unfortunately the ``displaySystem`` method cannot properly display such objects intersecting with each other.
 
 .. plot:: pyplots/examples/04_ComplexShape.py
    :include-source:

docs/pyplots/examples/00a_Trans.py

@@ -1,9 +1,8 @@
-from magpylib.source.magnet import Box
+import numpy as np
 import magpylib as magpy
-from numpy import array
-import matplotlib.pyplot as plt
+from magpylib.source.magnet import Box
 
-#fixed magnet parameters
+# fixed magnet parameters
 M = [0,0,1] #magnetization
 D = [2,2,2] #dimension
 
@@ -21,13 +20,10 @@
 s4.setPosition([2,0,-2])
 
 s5 = Box(mag=M, dim=D, pos = [ 4,0, 4])
-s5.position = array([4,0,0])
+s5.position = np.array([4,0,0])
 
 #collection
 c = magpy.Collection(s1,s2,s3,s4,s5)
 
 #display collection
-fig = magpy.displaySystem(c,suppress=True)
-fig.set_size_inches(6, 6)
-
-plt.show(fig)
+magpy.displaySystem(c,figsize=(6,6))

docs/pyplots/examples/00b_OrientRot1.py

@@ -1,18 +1,18 @@
 from magpylib.source.magnet import Box
 import magpylib as magpy
 
-#fixed magnet parameters
+# fixed magnet parameters
 M = [1,0,0] #magnetization
-D = [3,3,3] #dimension
+D = [4,2,2] #dimension
 
 # magnets with Euler angle orientations
 s1 = Box(mag=M, dim=D, pos = [-4,0, 4])
 s2 = Box(mag=M, dim=D, pos = [ 4,0, 4], angle=45, axis=[0,0,1])
 s3 = Box(mag=M, dim=D, pos = [-4,0,-4], angle=45, axis=[0,1,0])
 s4 = Box(mag=M, dim=D, pos = [ 4,0,-4], angle=45, axis=[1,0,0])
 
-#collection
+# collection
 c = magpy.Collection(s1,s2,s3,s4)
 
-#display collection
-magpy.displaySystem(c,direc=True)
+# display collection
+magpy.displaySystem(c,direc=True,figsize=(6,6))

docs/pyplots/examples/00c_OrientRot2.py

@@ -1,27 +1,27 @@
 import magpylib as magpy
 from magpylib.source.magnet import Box
 
-#fixed magnet parameters
+# fixed magnet parameters
 M = [0,0,1] #magnetization
 D = [3,3,3] #dimension
 
-#rotation axis
+# rotation axis
 rax = [-1,1,-1]
 
-#magnets with different orientations
+# magnets with different orientations
 s1 = Box(mag=M, dim=D, pos=[-6,0,4], angle=0, axis=rax)
 s2 = Box(mag=M, dim=D, pos=[ 0,0,4], angle=45, axis=rax)
 s3 = Box(mag=M, dim=D, pos=[ 6,0,4], angle=90, axis=rax)
 
-#magnets that are rotated differently
+# magnets that are rotated differently
 s4 =  Box(mag=M, dim=D, pos=[-6,0,-4])
 s5 =  Box(mag=M, dim=D, pos=[ 0,0,-4])
 s5.rotate(45,rax)
 s6 = Box(mag=M, dim=D, pos=[ 6,0,-4])
 s6.rotate(90,rax)
 
-#collect all
+# collect all sources
 c = magpy.Collection(s1,s2,s3,s4,s5,s6)
 
-#display collection
-magpy.displaySystem(c)
+# display collection
+magpy.displaySystem(c,figsize=(6,6))

docs/pyplots/examples/00d_OrientRot3.py

@@ -2,15 +2,15 @@
 from magpylib.source.magnet import Box
 import matplotlib.pyplot as plt
 
-#define figure
-fig = plt.figure(figsize=(5, 5))
+# define figure
+fig = plt.figure(figsize=(6,6))
 ax = fig.add_subplot(1,1,1, projection='3d')
 
-#fixed magnet parameters
+# fixed magnet parameters
 M = [0,0,1] #magnetization
 D = [2,4,1] #dimension
 
-#define magnets rotated with different pivot and anchor points
+# define magnets rotated with different pivot and anchor points
 piv1 = [-7,0,5]
 s1 = Box(mag=M, dim=D, pos = [-7,-3,5])
 
@@ -36,15 +36,19 @@
 s6 = Box(mag=M, dim=D, pos = [7,-3,-5])
 s6.rotate(-45,[0,0,1],anchor=anch6)
 
-#collect all sources
+# collect all sources
 c = magpy.Collection(s1,s2,s3,s4,s5,s6)
 
-#draw rotation axes
+# draw rotation axes
 for x in [-7,0,7]:
     for z in [-5,5]:
         ax.plot([x,x],[0,0],[z-3,z+4],color='.3')
 
-#display collection and markers
+# define markers
 Ms = [piv1+['piv1'], piv2+['piv2'], piv3+['piv3'], piv4+['piv4'],
       piv5+['piv5'], piv6+['piv6'], anch4+['anch4'],anch5+['anch5'],anch6+['anch6']]
-magpy.displaySystem(c,subplotAx=ax,markers=Ms)
+
+# display system
+magpy.displaySystem(c,subplotAx=ax,markers=Ms,suppress=True)
+
+plt.show()

docs/pyplots/examples/00e_ColTransRot.py

@@ -2,35 +2,36 @@
 from magpylib.source.current import Circular
 from numpy import linspace
 
-#windings of three parts of a coil at x/y = 0/0
-coil1a = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace( -3,-1,20)]
-coil1b = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace( -1, 1,20)]
-coil1c = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace(  1, 3,20)]
+# windings of three parts of a coil
+coil1a = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace( -3,-1,10)]
+coil1b = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace( -1, 1,10)]
+coil1c = [Circular(curr=1,dim=3,pos=[0,0,z]) for z in linspace(  1, 3,10)]
 
-#create collection and manipulate step by step
+# create collection and manipulate step by step
 c1 = magpy.Collection(coil1a)
 c1.move([-1,-1,0])
 c1.addSources(coil1b)
 c1.move([-1,-1,0])
 c1.addSources(coil1c)
 c1.move([-1,-1,0])
 
-#windings of three parts of another coil at x/y = 3/3
-coil2a = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace(-3,-1,20)]
-coil2b = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace( -1,1,20)]
-coil2c = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace( 1,3,20)]
+# windings of three parts of another coil
+coil2a = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace(-3,-1,15)]
+coil2b = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace( -1,1,15)]
+coil2c = [Circular(curr=1,dim=3,pos=[3,3,z]) for z in linspace( 1,3,15)]
 
-#create individual sub-collections
+# create individual sub-collections
 c2a = magpy.Collection(coil2a)
 c2b = magpy.Collection(coil2b)
 c2c = magpy.Collection(coil2c)
 
-#combine sub-collections to one big collection
+# combine sub-collections to one big collection
 c2 = magpy.Collection(c2a,c2b,c2c)
 
-#still manipulate each individual sub-collection
+# still manipulate each individual sub-collection
 c2a.rotate(-15,[1,-1,0],anchor=[0,0,0])
 c2c.rotate(15,[1,-1,0],anchor=[0,0,0])
 
-#combine all collectins and display system
-magpy.displaySystem([c1,c2])
+# combine all collections and display system
+c3 = magpy.Collection(c1,c2)
+magpy.displaySystem(c3,figsize=(6,6))

docs/pyplots/examples/01_SimpleCollection.py

@@ -5,8 +5,8 @@
 
 # create figure
 fig = plt.figure(figsize=(8,4))
-ax1 = fig.add_subplot(121, projection='3d')
-ax2 = fig.add_subplot(122)
+ax1 = fig.add_subplot(121, projection='3d')  # this is a 3D-plotting-axis
+ax2 = fig.add_subplot(122)                   # this is a 2D-plotting-axis
 
 # create magnets
 s1 = magpy.source.magnet.Box(mag=[0,0,600],dim=[3,3,3],pos=[-4,0,3])
@@ -19,7 +19,7 @@
 # create collection
 c = magpy.Collection(s1,s2)
 
-# display system geometry
+# display system geometry on ax1
 magpy.displaySystem(c,subplotAx=ax1,suppress=True)
 
 # calculate B-field on a grid

docs/pyplots/examples/01b_AllSources.py

@@ -1,9 +1,8 @@
 import magpylib as magpy
-from numpy import array, linspace, meshgrid
-from numpy.linalg import norm
+import numpy as np
 from matplotlib import pyplot as plt
 
-#set font size and define figures
+# set font size and define figures
 plt.rcParams.update({'font.size': 6})
 
 fig1 = plt.figure(figsize=(8, 5))
@@ -14,12 +13,12 @@
 axsA += [fig2.add_subplot(2,3,i, projection='3d') for i in range(1,4)]
 axsB += [fig2.add_subplot(2,3,i) for i in range(4,7)]
 
-#position grid
-ts = linspace(-6,6,50)
-posis = array([(x,0,z) for z in ts for x in ts])
-X,Y = meshgrid(ts,ts)
+# position grid
+ts = np.linspace(-6,6,50)
+posis = np.array([(x,0,z) for z in ts for x in ts])
+X,Y = np.meshgrid(ts,ts)
 
-# source definitions
+# create the source objects
 s1 = magpy.source.magnet.Box(mag=[500,0,500], dim=[4,4,4])                #Box
 s2 = magpy.source.magnet.Cylinder(mag=[0,0,500], dim=[3,5])               #Cylinder
 s3 = magpy.source.magnet.Sphere(mag=[-200,0,500], dim=5)                  #Sphere
@@ -29,14 +28,13 @@
 
 for i,s in enumerate([s1,s2,s3,s4,s5,s6]):
 
-    #plot geometry in memory
+    # display system on respective axes, use marker to zoom out
     magpy.displaySystem(s,subplotAx=axsA[i],markers=[(6,0,6)],suppress=True)
     axsA[i].plot([-6,6,6,-6,-6],[0,0,0,0,0],[-6,-6,6,6,-6])
 
-    #plot field in memory
-    B = array([s.getB(p) for p in posis]).reshape(50,50,3)
-    axsB[i].pcolor(X,Y,norm(B,axis=2),cmap=plt.cm.get_cmap('coolwarm'))
-    axsB[i].streamplot(X, Y, B[:,:,0], B[:,:,2], color='k',linewidth=1)
+    # plot field on respective axes
+    B = np.array([s.getB(p) for p in posis]).reshape(50,50,3)
+    axsB[i].pcolor(X,Y,np.linalg.norm(B,axis=2),cmap=plt.cm.get_cmap('coolwarm'))   # amplitude
+    axsB[i].streamplot(X, Y, B[:,:,0], B[:,:,2], color='k',linewidth=1)             # field lines
 
-#display plots
 plt.show()