==============
Usage of PySRW
==============

A SRW simulation consists of two distinct stages

* the :doc:`emission <emission>` stage is the creation of the :py:class:`~pysrw.wavefronts.Wavefront` 
  object which describes the electric field emitted by a source onto an 
  :py:class:`~pysrw.wavefronts.Observer` mesh;
* the field can be the input of a :doc:`propagation <propagation>` stage which transports the wavefront
  through a sequence of optical elements, using Physical Optics Propagation algorithms.

Refer to the respective sections for detailed information on configuring and setting up these two stages!

.. tip:: 

    Emission and propagation are quite independent stages. You may not need the propagation if you are
    just interested in properties of the wavefront emitted by the source and, on the other hand, you may
    use the POP functionalities to propagate a custom field which was not simulated in SRW.

Quickstart
==========

The first thing you need to do is importing the module. The standard way is

.. code-block:: python

    import pysrw as srw

Unless you're working with electrons (the default), you'll need to set the particle type. 
Options include 'electron', 'proton', and 'lead' (Pb208 ions), which are standard particles at CERN. 
Alternatively, you can define a custom particle by specifying its charge and mass. 
To modify the library configuration, use :py:meth:`~pysrw.configuration.CONFIG.initParticleType`

.. code-block:: python

    srw.CONFIG.initParticleType(particleType='proton')

The particle initialization must be done at the top of your script as it impacts many simulation parameters.

.. note::

    If you prefer working with the original SRW binding, it may be more convenient to directly 
    import :ref:`srwlib <pysrw.lib.srwlib>` as ``import pysrw.lib.srwlib as srw``.

You are now ready to write your first simulation script!

.. toctree::
    :hidden:

    Emission <emission>
    Propagation <propagation>
    Additional information <miscellanea>