v 1.5.0

doc/conf.py

@@ -16,7 +16,7 @@
     class Mock(MagicMock):
         @classmethod
         def __getattr__(cls, name):
-                return MagicMock()
+            return MagicMock()
 
     MOCK_MODULES = ['OpenGL', 'OpenGL.GL', 'OpenGL.GLU', 'OpenGL.GLUT',
                     'OpenGL.arrays', 'pyopencl',
@@ -141,9 +141,9 @@ def load_res():
 # built documents.
 #
 # The short X.Y version.
-version = '1.4.0'
+version = '1.5.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.4.0'
+release = '1.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -4,10 +4,10 @@
 # import importLongDescription
 # long_description = importLongDescription.output()
 long_description = u"""
-Package xrt (XRayTracer) is a python software library for ray tracing and wave
-propagation in x-ray regime. It is primarily meant for modeling synchrotron
-sources, beamlines and beamline elements. Includes a GUI for creating a
-beamline and interactively viewing it in 3D.
+Package xrt is a python software library for ray tracing and wave propagation
+in x-ray regime. It is primarily meant for modeling synchrotron sources,
+beamlines and beamline elements. Includes a GUI for creating a beamline and
+interactively viewing it in 3D.
 
 Features of xrt
 ---------------
@@ -17,6 +17,8 @@
   lens or paraxial. The optical surfaces may have figure errors, analytical or
   measured. In wave propagation, partially coherent radiation is treated by
   incoherent addition of coherently diffracted fields generated per electron.
+  Propagation of _individual_ coherent source modes is possible as waves,
+  hybrid waves (i.e. partially as rays and then as waves) and only rays.
 
 * *Publication quality graphics*. 1D and 2D position histograms are
   *simultaneously* coded by hue and brightness. Typically, colors represent
@@ -42,34 +44,31 @@
   throughout the series.
 
 * *Synchrotron sources*. Bending magnet, wiggler, undulator and elliptic
-  undulator are calculated internally within xrt. There is also a legacy
-  approach to sampling synchrotron sources using the codes `ws` and `urgent`
-  which are parts of XOP package. Please look the section "Comparison of
-  synchrotron source codes" for the comparison between the implementations. If
-  the photon source is one of the synchrotron sources, the total flux in the
-  beam is reported not just in number of rays but in physical units of ph/s.
-  The total power or absorbed power can be opted instead of flux and is
+  undulator are calculated internally within xrt. Please look the section
+  "Comparison of synchrotron source codes" for the comparison other popular
+  codes. If the photon source is one of the synchrotron sources, the total flux
+  in the beam is reported not just in number of rays but in physical units of
+  ph/s. The total power or absorbed power can be opted instead of flux and is
   reported in W. The power density can be visualized by isolines. The magnetic
   gap of undulators can be tapered. Undulators can be calculated in near field.
   Custom magnetic field is also possible. Undulators can be calculated on GPU,
   with a high gain in computation speed, which is important for tapering and
   near field calculations.
 
 * *Shapes*. There are several predefined shapes of optical elements implemented
-  as python classes. The inheritance mechanism simplifies creation of other
-  shapes. The user specifies methods for the surface height and the surface
-  normal. For asymmetric crystals, the normal to the atomic planes can be
-  additionally given. The surface and the normals are defined either in local
-  (x, y) coordinates or in user-defined parametric coordinates. Parametric
+  as python classes. The python inheritance mechanism simplifies creation of
+  other shapes: the user specifies methods for surface height and surface
+  normal. The surface and the normal are defined either in local Cartesian
+  coordinates or in user-defined parametric coordinates. Parametric
   representation enables closed shapes such as capillaries or wave guides. It
-  also enables exact solutions for complex shapes (e.g. a logarithmic spiral)
-  without any expansion. The methods of finding the intersections of rays with
-  the surface are very robust and can cope with pathological cases as sharp
-  surface kinks. Notice that the search for intersection points does not
-  involve any approximation and has only numerical inaccuracy which is set by
-  default as 1 fm. Any surface can be combined with a (differently and variably
-  oriented) crystal structure and/or (variable) grating vector. Surfaces can be
-  faceted.
+  also enables exact solutions for complex shapes (e.g. a logarithmic spiral or
+  an ellipsoid) without any expansion. The methods of finding the intersections
+  of rays with the surface are very robust and can cope with pathological cases
+  such as sharp surface kinks. Notice that the search for intersection points
+  does not involve any approximation and has only numerical inaccuracy which is
+  set by default as 1 fm. Any surface can be combined with a (differently and
+  variably oriented) crystal structure and/or (variable) grating vector.
+  Surfaces can be faceted.
 
 * *Energy dispersive elements*. Implemented are crystals in dynamical
   diffraction, gratings (also with efficiency calculations), Fresnel zone
@@ -118,17 +117,16 @@
 -------------------------------------
 
 The main interface to xrt is through a python script. Many examples of such
-scripts can be found in the supplied folder 'examples'. The script imports the
-modules of xrt, instantiates beamline parts, such as synchrotron or geometric
-sources, various optical elements, apertures and screens, specifies required
-materials for reflection, refraction or diffraction, defines plots and sets job
-parameters.
-
-The Qt tool xrtQook takes these ingredients and prepares a ready to use script
-that can be run within the tool itself or in an external Python context.
-xrtQook features a parallelly updated help panel that, unlike the main
-documentation, provides a complete list of parameters for the used classes,
-also including those from the parental classes. xrtQook writes/reads the
+scripts can be found in the supplied folders 'examples' and 'tests'. The script
+imports the modules of xrt, instantiates beamline parts, such as synchrotron or
+geometric sources, various optical elements, apertures and screens, specifies
+required materials for reflection, refraction or diffraction, defines plots and
+sets job parameters.
+
+The Qt tool xrtQook takes these ingredients as GUI elements and prepares a
+ready to use script that can be run within the tool itself or in an external
+Python context. xrtQook has a parallelly updated help panel that provides a
+complete list of parameters for the used objects. xrtQook writes/reads the
 recipes of beamlines into/from xml files.
 
 xrtGlow -- an interactive 3D beamline viewer
@@ -154,12 +152,6 @@
 for xrtQook. Spyder (as library of Spyder IDE) is highly recommended for nicer
 view of xrtQook. OpenGL is required for xrtGlow.
 
-Python 2 and 3
---------------
-
-The code should run in both Python branches without any modification, although
-compatibility with Python 2 is not checked any longer.
-
 Get xrt
 -------
 
@@ -180,7 +172,7 @@
 
 setup(
     name='xrt',
-    version='1.4.0',
+    version='1.5.0',
     description='Ray tracing and wave propagation in x-ray regime, primarily '
                 'meant for modeling synchrotron sources, beamlines and '
                 'beamline elements. Includes a GUI for creating a beamline '

xrt/__init__.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
-u"""Package xrt (XRayTracer) is a python software library for ray tracing and
-wave propagation in x-ray regime. It is primarily meant for modeling
-synchrotron sources, beamlines and beamline elements. Includes a GUI for
-creating a beamline and interactively viewing it in 3D.
+u"""
+Package xrt is a python software library for ray tracing and wave propagation
+in x-ray regime. It is primarily meant for modeling synchrotron sources,
+beamlines and beamline elements. Includes a GUI for creating a beamline and
+interactively viewing it in 3D.
 
 +----------------+---------------+-----------+
 |     |Itot|     |   |vcmSi-P|   | |VortexB| |
@@ -34,7 +35,9 @@
   such as thin lens or paraxial. The optical surfaces may have :ref:`figure
   errors, analytical or measured<warping>`. In wave propagation, partially
   coherent radiation is treated by incoherent addition of coherently diffracted
-  fields generated per electron.
+  fields generated per electron. Propagation of :ref:`individual coherent
+  source modes<modes>` is possible as waves, hybrid waves (i.e. partially as
+  rays and then as waves) and only rays.
 
 * *Publication quality graphics*. 1D and 2D position histograms are
   *simultaneously* coded by hue and brightness. Typically, colors represent
@@ -61,36 +64,33 @@
   throughout the series.
 
 * :ref:`Synchrotron sources <synchrotron-sources>`. Bending magnet, wiggler,
-  undulator and elliptic undulator are calculated internally within xrt. There
-  is also a legacy approach to sampling synchrotron sources using the codes
-  `ws` and `urgent` which are parts of XOP package. Please look the section
-  :ref:`comparison-synchrotron-sources` for the comparison between the
-  implementations. If the photon source is one of the synchrotron sources, the
-  total flux in the beam is reported not just in number of rays but in physical
-  units of ph/s. The total power or absorbed power can be opted instead of flux
-  and is reported in W. The power density can be visualized by isolines. The
-  magnetic gap of undulators can be :ref:`tapered <tapering_comparison>`.
-  Undulators can be calculated in :ref:`near field <near_field_comparison>`.
-  :ref:`Custom magnetic field <undulator_custom>` is also possible. Undulators
-  can be :ref:`calculated on GPU <calculations_on_GPU>`, with a high gain in
-  computation speed, which is important for tapering and near field
-  calculations.
+  undulator and elliptic undulator are calculated internally within xrt.
+  Please look the section :ref:`comparison-synchrotron-sources` for the
+  comparison with other popular codes. If the photon source is one of the
+  synchrotron sources, the total flux in the beam is reported not just in
+  number of rays but in physical units of ph/s. The total power or absorbed
+  power can be opted instead of flux and is reported in W. The power density
+  can be visualized by isolines. The magnetic gap of undulators can be
+  :ref:`tapered <tapering_comparison>`. Undulators can be calculated in
+  :ref:`near field <near_field_comparison>`. :ref:`Custom magnetic field
+  <undulator_custom>` is also possible. Undulators can be :ref:`calculated on
+  GPU <calculations_on_GPU>`, with a high gain in computation speed, which is
+  important for tapering and near field calculations.
 
 * *Shapes*. There are several predefined shapes of optical elements implemented
-  as python classes. The inheritance mechanism simplifies creation of other
-  shapes. The user specifies methods for the surface height and the surface
-  normal. For asymmetric crystals, the normal to the atomic planes can be
-  additionally given. The surface and the normals are defined either in local
-  (x, y) coordinates or in user-defined parametric coordinates. Parametric
+  as python classes. The python inheritance mechanism simplifies creation of
+  other shapes: the user specifies methods for surface height and surface
+  normal. The surface and the normal are defined either in local Cartesian
+  coordinates or in user-defined parametric coordinates. Parametric
   representation enables closed shapes such as capillaries or wave guides. It
-  also enables exact solutions for complex shapes (e.g. a logarithmic spiral)
-  without any expansion. The methods of finding the intersections of rays with
-  the surface are very robust and can cope with pathological cases as sharp
-  surface kinks. Notice that the search for intersection points does not
-  involve any approximation and has only numerical inaccuracy which is set by
-  default as 1 fm. Any surface can be combined with a (differently and variably
-  oriented) crystal structure and/or (variable) grating vector. Surfaces can be
-  faceted.
+  also enables exact solutions for complex shapes (e.g. a logarithmic spiral or
+  an ellipsoid) without any expansion. The methods of finding the intersections
+  of rays with the surface are very robust and can cope with pathological cases
+  such as sharp surface kinks. Notice that the search for intersection points
+  does not involve any approximation and has only numerical inaccuracy which is
+  set by default as 1 fm. Any surface can be combined with a (differently and
+  variably oriented) crystal structure and/or (variable) grating vector.
+  Surfaces can be faceted.
 
 * *Energy dispersive elements*. Implemented are :meth:`crystals in dynamical
   diffraction <xrt.backends.raycing.materials.Crystal.get_amplitude>`,
@@ -143,12 +143,6 @@
   :ref:`undulators <mesh-methods>`, :ref:`optical elements <test_oes>`,
   :ref:`materials <test_materials>` and :ref:`wave propagation <test_waves>`.
 
-Python 2 and 3
---------------
-
-The code should run in both Python branches without any modification, although
-compatibility with Python 2 is not checked any longer.
-
 Dependencies
 ------------
 

xrt/gui/xrtQook/__init__.py

@@ -6,18 +6,17 @@
 ----------------------------------------
 
 The main interface to xrt is through a python script. Many examples of such
-scripts can be found in the supplied folder ‘examples’. The script imports the
-modules of xrt, instantiates beamline parts, such as synchrotron or geometric
-sources, various optical elements, apertures and screens, specifies required
-materials for reflection, refraction or diffraction, defines plots and sets job
-parameters.
-
-The Qt tool :mod:`xrtQook` takes these ingredients and prepares a ready to use
-script that can be run within the tool itself or in an external Python context.
-:mod:`xrtQook` features a parallelly updated help panel that provides a
-complete list of parameters for the used classes, also including those from the
-parental classes. :mod:`xrtQook` writes/reads the recipes of beamlines
-into/from xml files.
+scripts can be found in the supplied folders `examples` and `tests`. The script
+imports the modules of xrt, instantiates beamline parts, such as synchrotron or
+geometric sources, various optical elements, apertures and screens, specifies
+required materials for reflection, refraction or diffraction, defines plots and
+sets job parameters.
+
+The Qt tool :mod:`xrtQook` takes these ingredients as GUI elements and prepares
+a ready to use script that can be run within the tool itself or in an external
+Python context. :mod:`xrtQook` has a parallelly updated help panel that
+provides a complete list of parameters for the used objects. :mod:`xrtQook`
+writes/reads the recipes of beamlines into/from xml files.
 
 In the present version, :mod:`xrtQook` does not provide automated generation of
 *scans* and does not create *wave propagation* sequences. For these two tasks,

xrt/version.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
-__versioninfo__ = (1, 4, 0)
+__versioninfo__ = (1, 5, 0)
 __version__ = '.'.join(map(str, __versioninfo__))
-__date__ = "22 Sep 2021"
+__date__ = "8 Sep 2022"