==================
Radiation emission
==================

The output of the emission stage is the :py:class:`~pysrw.wavefronts.Wavefront`. 
This describes the two transverse components of the complex electric field emitted
by a source. The computation of the wavefront depends on the type of source you are
using in your simulation.

Point source and Gaussian beam
------------------------------

If you are working with one of these emitters, creating the wavefront is straightforward.
You just need to instantiate the class, :py:class:`~pysrw.emitters.PointSource` or 
:py:class:`~pysrw.emitters.GaussianBeam` respectively, to create your emitter and 
define an observation mesh with :py:class:`~pysrw.wavefronts.Observer`.

The field computation is performed with the corresponding functions 
:py:func:`~pysrw.computations.computePtSrcWfr` or :py:func:`~pysrw.computations.computeGsnBeamWfr`.
These are also available as multiprocessing computation :py:func:`~pysrw.computations.computePtSrcWfrMultiProcess` or 
:py:func:`~pysrw.computations.computeGsnBeamWfrMultiProcess`.

Check the examples :doc:`../examples/point_source` and :doc:`../examples/gaussian_beam` for practical case!

Synchrotron radiation wavefront
-------------------------------

The computation of a synchrotron radiation wavefront requires information about the 
particle beam and the magnetic structure.

A particle beam is an instance of :py:class:`~pysrw.emitters.ParticleBeam`, which requires the 
parameters of the particle distribution and the initial conditions 
for the trajectory computation (position and angle).

The individual magnetic devices are created using the classes listed in :ref:`magnets <pysrw.magnets>`.
These are then collected in a :py:class:`~pysrw.magnets.MagnetsContainer` which represents the 
final magnetic structure. The magnet container also defines the parameters required for the field 
computation, namely the start, end and discretization of the trajectory integration.

An :py:class:`~pysrw.wavefronts.Observer` is finally needed to define the observation mesh.

The diagram below gives you a quick overview of the objects involved and how they're connected.

.. image:: ../_static/sim_layout.svg
    :align: center

These objects are passed to the :py:func:`~pysrw.computations.computeSrWfr` function, 
responsible for integrating the particle trajectory and providing the simulated field as output. 
The multiprocessing computation is also available with :py:func:`~pysrw.computations.computeSrWfrMultiProcess`.
It is crucial to carefully configure simulation parameters, including integration limits, field approximations, 
and wavelength settings. Incorrect parameterization can lead to issues such as simulation crashes, hang-ups, or, 
worst-case scenario, plausible but actually wrong results. 
Although emission computation in SRW is typically robust, thorough validation is essential. 
Play with different simulation parameters to validate results to ensure they are unaffected by variations in the 
computation parameters.

Check the examples :doc:`../examples/simple_dipole` and :doc:`../examples/simple_undulator` to familiarize with 
the fundamentals of synchrotron radiation emission!


Coordinate frame
^^^^^^^^^^^^^^^^

It is important to understand the definition of the coordinate frame:

* the location of each **magnet** is defined by the position of its centre in the 3D space (x,y,z).
* the position of the **beam** is defined by its initial condition (IC), namely a (x,y,z) 
  position and (x', y.) angle. In the example above, the IC is put with zero angles on a point 
  with zero transverse positions and a z between the two single dipoles. This produces a beam that
  travels along the longitudinal azis in the straight section betwen the dipoles.
* the **observer** is always perpendicular to the longitudinal axis and its transverse position, extension 
  and spatial resolution (or binning) are defined with the corresponding arguments.

The definiton of the container limits is a crucial aspect of the emission simulation. Assuming that the 
lenght of a magnet container is the distance between the edge of the left-most element and the 
edge of the right-most one, the default integration limits are computing adding a margin of the 
same length aroung these values. For example, if the container ranges from z=-3m to z=+5m, the integration
is performed between z=-7m and z=9m. These values can be changed in the definition of the container, 
either specifying a different fraction ror the extra margin or by forcing the limits to two fixed values.

.. warning:: **Longitudinal and curvilinear coordinates!**

    If you are computing the trajectory of a particle beam with
    :py:func:`~pysrw.computations.computeTrajectory`, you need to provide computation limits in 
    the curvilinear coordinate s, where the origin s=0 coincides with the beam IC in the 3D (x,y,z) space.
    For example, a beam with IC at z=2 and a trajectory between s=-2 and s=2 will track the particle 
    motion between 2m upstream of the IC and 2m downstream of it, along the curvilinear coordinate.
    Check the example :doc:`../examples/coordinates` to learn the differences!

There are two main constraints regarding the element positions

#. the z position of the beam IC must lie within the integration limits of the container. 
   Locations inside a region with non-zero magnetic field are allowed;
#. the z position of the observer must be downstream of the magnet container.