xrt 2.0.0b0__py3-none-any.whl

xrt/__init__.py

@@ -0,0 +1,247 @@
+# -*- coding: utf-8 -*-
+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| |
++----------------+---------------+-----------+
+
+.. |Itot| animationhover:: _images/Itot
+   :alt:  Intensity of undulator radiation on a transverse flat screen.
+       The long axis is energy. One can observe two harmonics crossing the
+       central line: the one at 2400 eV is odd and the one at 4800 eV is even.
+
+.. |vcmSi-P| animationhover:: _images/vcmSi-FootprintP
+   :alt:  Absorbed power and power density on a mirror at varying pitch
+       angle.
+   :loc: upper-right-corner
+
+.. |VortexB| animationhover:: _images/Laguerre-Gauss-ani
+   :alt: &ensp;Vortex beam with <i>l</i>=1 and <i>p</i>=1. Colored by phase.
+   :loc: upper-right-corner
+
+.. _guis:
+
+GUIs
+----
+
+.. tabs::
+
+   .. tab:: xrtQook
+       .. automodule:: xrt.gui.xrtQook
+
+   .. tab:: xrtGlow
+       .. automodule:: xrt.gui.xrtGlow
+
+   .. tab:: xrtBentXtal
+       .. automodule:: xrt.gui.xrtBentXtal
+
+Features of xrt
+---------------
+
+* *Rays and waves*. Classical ray tracing and :ref:`wave propagation <waves>`
+  via Kirchhoff integrals, also freely intermixed. No further approximations,
+  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. 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
+  energy and brightness represents beam intensity. The user may select other
+  quantities to be encoded by colors: angular and positional distributions,
+  various polarization properties, beam categories, number of reflections,
+  incidence angle etc. Brightness can also encode partial flux for a selected
+  polarization and incident or absorbed power. Publication quality plots are
+  provided by `matplotlib <http://matplotlib.org>`_ with image formats PNG,
+  PostScript, PDF and SVG.
+
+* *Unlimited number of rays*. The colored histograms are *cumulative*. The
+  accumulation can be stopped and resumed.
+
+* *Parallel execution*. xrt can be run :ref:`in parallel <tests>` in several
+  threads or processes (can be opted), which accelerates the execution on
+  multi-core computers. Alternatively, xrt can use the power of GPUs via OpenCL
+  for running special tasks such as the calculation of an undulator source or
+  performing wave propagation.
+
+* *Scripting in Python*. xrt can be run within Python scripts to generate a
+  series of images under changing geometrical or physical parameters. The image
+  brightness and 1D histograms can be normalized to the global maximum
+  throughout the series.
+
+* :ref:`Synchrotron sources <synchrotron-sources>`. Bending magnet, wiggler,
+  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 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 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>`,
+  gratings (also with efficiency calculations), Fresnel zone plates,
+  Bragg-Fresnel optics and :meth:`multilayers in dynamical diffraction
+  <xrt.backends.raycing.materials.Multilayer.get_amplitude>`. Crystals can work
+  in Bragg or Laue cases, in reflection or in transmission. The
+  two-field polarization phenomena are fully preserved, also within the Darwin
+  diffraction plateau, thus enabling the ray tracing of crystal-based phase
+  retarders.
+
+* *Materials*. The material properties are incorporated using :class:`three
+  different tabulations <xrt.backends.raycing.materials.Material>` of the
+  scattering factors, with differently wide and differently dense energy
+  meshes. Refractive index and absorption coefficient are calculated from the
+  scattering factors. Two-surface bodies, such as plates or refractive lenses,
+  are treated with both refraction and absorption.
+
+* *Multiple reflections*. xrt can trace multiple reflections in a single
+  optical element. This is useful, for example in 'whispering gallery' optics
+  or in Montel or Wolter mirrors.
+
+* *Non-sequential optics*. xrt can trace non-sequential optics where different
+  parts of the incoming beam meet different surfaces. Examples of such optics
+  are :ref:`poly-capillaries<polycapillary>` and Wolter mirrors.
+
+* *Singular optics*. xrt correctly propagates :ref:`vortex beams
+  <test-Laguerre-Gaussian>`, which can be used for studying the creation of
+  vortex beams by transmissive or reflective optics.
+
+* *Global coordinate system*. The optical elements are positioned in a global
+  coordinate system. This is convenient for modeling a real synchrotron
+  beamline. The coordinates in this system can be directly taken from a CAD
+  library. The optical surfaces are defined in their local systems for the
+  user's convenience.
+
+* *Beam categories*. xrt discriminates rays by several categories: `good`,
+  `out`, `over` and `dead`. This distinction simplifies the adjustment of
+  entrance and exit slits. An alarm is triggered if the fraction of dead rays
+  exceeds a specified level.
+
+* *Portability*. xrt runs on Windows and Unix-like platforms, wherever you can
+  run python.
+
+* *Examples*. xrt comes with many examples. See the galleries, the links are at
+  the top bar.
+
+* *Tests*. xrt comes with the tests of its several main aspects. See the folder
+  `tests` and also this documentation for the tests of
+  :ref:`undulators <mesh-methods>`, :ref:`optical elements <test_oes>`,
+  :ref:`materials <test_materials>` and :ref:`wave propagation <test_waves>`.
+
+Installation
+------------
+
+Install it by pip or conda or get xrt from
+`GitHub <https://github.com/kklmn/xrt>`_ and use it with or without
+installation. See :ref:`detailed installation instructions <instructions>`.
+
+The distribution archive also includes tests and examples. The complete
+documentation is available online on
+`Read the Docs <http://xrt.readthedocs.io>`_ and offline as
+`zip file on GitHub <https://github.com/kklmn/xrt-docs>`_.
+
+Get help
+--------
+
+For getting help and/or reporting a bug please use `GitHub xrt Issues
+<https://github.com/kklmn/xrt/issues>`_.
+
+Citing xrt
+----------
+
+Please cite xrt as:
+`K. Klementiev and R. Chernikov, "Powerful scriptable ray tracing package xrt",
+Proc. SPIE 9209, Advances in Computational Methods for X-Ray Optics III,
+92090A (2014); doi:10.1117/12.2061400 <http://dx.doi.org/10.1117/12.2061400>`_.
+`Online documentation on xrt.readthedocs.io;
+doi:10.5281/zenodo.1252468 <https://doi.org/10.5281/zenodo.1252468>`_.
+
+For the new capabilities:
+1) Calculations of elastically deformed crystals on GPUs,
+2) Mode analysis and mode propagation,
+3) Modelling OAM (Orbital Angular Momentum) beams,
+please cite:
+`K. Klementiev & R. Chernikov, "New Features of xrt: Bent Crystals, Coherent
+Modes, Waves with OAM" Synchrotron Radiation News (2023) 36:5, 23-27;
+doi:10.1080/08940886.2023.2274735
+<https://doi.org/10.1080/08940886.2023.2274735>`_.
+
+Acknowledgments
+---------------
+
+* Josep Nicolás and Jordi Juanhuix (synchrotron Alba) are acknowledged for
+  discussion and for their Matlab codes used as examples at early stages of the
+  project.
+
+* Andrew Geondzhian and Victoria Kabanova (summer students at DESY) are
+  acknowledged for their help in coding the classes of synchrotron sources.
+
+* Rami Sankari and Alexei Preobrajenski (MAX IV Laboratory) are thanked for
+  discussion, testing and comparing with external codes.
+
+* Hasan Yavaş, Jozef Bednarčik, Dmitri Novikov and Alexey Zozulya (DESY Photon
+  Science) are acknowledged for supplied cases.
+
+* Hamed Tarawneh (MAX IV Laboratory) has initiated the custom field undulator
+  project and supplied tables of magnetic field.
+
+* Bernard Kozioziemski (LLNL) has pointed to the importance of considering
+  the *total* absorption cross-section (not just photoelectric absorption) in
+  the cases of light materials at high energy. He also did deep tests of the
+  mosaic crystal model.
+
+* Emilio Heredia (CLS) is thanked for valuable suggestions on GUI.
+
+* Tim May (CLS) is acknowledged for inspiring the custom magnetic field
+  calculation development, providing field tables and comparing the results
+  with other codes.
+
+* Louisa Pickworth (MAX IV Laboratory) has provided curves from other codes for
+  testing reflectivity/transmittivity of multilayers.
+
+"""
+
+# ========Convention: note the difference from PEP8 for variables!=============
+# Naming:
+#   * classes MixedUpperCase
+#   * varables lowerUpper _or_ lower
+#   * functions and methods underscore_separated _or_ lower
+# =============================================================================
+
+from .version import __versioninfo__, __version__, __date__
+__module__ = "xrt"
+__author__ = \
+    "Konstantin Klementiev (MAX IV Laboratory), " +\
+    "Roman Chernikov (NSLS-II)"
+__email__ = "konstantin DOT klementiev AT gmail DOT com, " +\
+            "rchernikov AT gmail DOT com"
+__license__ = "MIT license"
+
+# __all__ = ['plotter', 'runner', 'multipro']

xrt/backends/__init__.py

@@ -0,0 +1 @@
+pass

xrt/backends/dummy.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+Module :mod:`dummy` represents the simplest backend with the minimum output
+required for building histograms. You can use this backend to generate your
+simple examples, as exemplified in ``xrt_logo.py``::
+
+    def local_output():
+        # define your (x, y, intensity, cData, locNrays) here
+        return x, y, intensity, energy, locNrays
+    dummy.run_process = local_output #is invoked by xrt to get the rays
+"""
+import numpy as np
+
+nrays = 25000
+
+
+def run_process(nrays=nrays):
+    nrays = int(nrays)
+    x = np.random.normal(size=nrays)
+    y = np.random.normal(size=nrays)
+    intensity = np.ones_like(x)
+    energy = x + y * 2.0 + 5000
+#    energy = np.random.uniform(4998, 5002, size=locNrays)
+    return x, y, intensity, energy, nrays