add particle spin

[Alfven17]

add particle spin for ParticleGroup

[DavidSagan]

It is in the standard.

[ColwynGulliford]

Has there been any progress on this? I have two projects that could use spin.

[ColwynGulliford]

@DavidSagan it is in the standard perhaps, but its not in implemented on the Python side, so I would not close this issue.

#-----------------------------------------
# Classes

class ParticleGroup:
    """
    Particle Group class

    Initialized on on openPMD beamphysics particle group:

    - **h5**: open h5 handle, or `str` that is a file
    - **data**: raw data

    The required bunch data is stored in `.data` with keys

    - `np.array`: `x`, `px`, `y`, `py`, `z`, `pz`, `t`, `status`, `weight`
    - `str`: `species`

    where:

    - `x`, `y`, `z` are positions in units of [m]
    - `px`, `py`, `pz` are momenta in units of [eV/c]
    - `t` is time in [s]
    - `weight` is the macro-charge weight in [C], used for all statistical calulations.
    - `species` is a proper species name: `'electron'`, etc. 

    Optional data:

    - `np.array`: `id`

    where `id` is a list of unique integers that identify the particles. 

    Derived data can be computed as attributes:

    - `.gamma`, `.beta`, `.beta_x`, `.beta_y`, `.beta_z`: relativistic factors [1].
    - `.r`, `.theta`: cylidrical coordinates [m], [1]
    - `.pr`, `.ptheta`: momenta in the radial and angular coordinate directions [eV/c]
    - `.Lz`: angular momentum about the z axis [m*eV/c]
    - `.energy` : total energy [eV]
    - `.kinetic_energy`: total energy - mc^2 in [eV]. 
    - `.higher_order_energy`: total energy with quadratic fit in z or t subtracted [eV]
    - `.p`: total momentum in [eV/c]
    - `.mass`: rest mass in [eV]
    - `.xp`, `.yp`: Slopes $x' = dx/dz = dp_x/dp_z$ and $y' = dy/dz = dp_y/dp_z$ [1].

    Normalized transvere coordinates can also be calculated as attributes:

    - `.x_bar`, `.px_bar`, `.y_bar`, `.py_bar` in [sqrt(m)]

    The normalization is automatically calculated from the covariance matrix. 
    See functions in `.statistics` for more advanced usage.

    Their cooresponding amplitudes are:

    `.Jx`, `.Jy` [m]

    where `Jx = (x_bar^2 + px_bar^2 )/2`.

    The momenta are normalized by the mass, so that
    `<Jx> = norm_emit_x`
    and similar for `y`. 

    Statistics of any of these are calculated with:

    - `.min(X)`
    - `.max(X)`
    - `.ptp(X)`
    - `.avg(X)`
    - `.std(X)`
    - `.cov(X, Y, ...)`
    - `.histogramdd(X, Y, ..., bins=10, range=None)`

    with a string `X` as the name any of the properties above.

    Useful beam physics quantities are given as attributes:

    - `.norm_emit_x`
    - `.norm_emit_y`
    - `.norm_emit_4d`
    - `.higher_order_energy_spread`
    - `.average_current`

    Twiss parameters, including dispersion, for the $x$ or $y$ plane:

    - `.twiss(plane='x', fraction=0.95, p0C=None)`

    For convenience, `plane='xy'` will calculate twiss for both planes.

    Twiss matched particles, using a simple linear transformation:

    - `.twiss_match(self, beta=None, alpha=None, plane='x', p0c=None, inplace=False)`

    The weight is required and must sum to > 0. The sum of the weights is in `.charge`.
    This can also be set: `.charge = 1.234` # C, will rescale the .weight array

    All attributes can be accessed with brackets:
        `[key]`

    Additional keys are allowed for convenience:
        `['min_prop']`   will return  `.min('prop')`
        `['max_prop']`   will return  `.max('prop')`
        `['ptp_prop']`   will return  `.ptp('prop')`
        `['mean_prop']`  will return  `.avg('prop')`
        `['sigma_prop']` will return  `.std('prop')`
        `['cov_prop1__prop2']` will return `.cov('prop1', 'prop2')[0,1]`

    Units for all attributes can be accessed by:

    - `.units(key)`

    Particles are often stored at the same time (i.e. from a t-based code), 
    or with the same z position (i.e. from an s-based code.)
    Routines: 

    - `drift_to_z(z0)`
    - `drift_to_t(t0)`

    help to convert these. If no argument is given, particles will be drifted to the mean.
    Related properties are:

    - `.in_t_coordinates` returns `True` if all particles have the same $t$ corrdinate
    - `.in_z_coordinates` returns `True` if all particles have the same $z$ corrdinate

    Convenient plotting is provided with: 

    - `.plot(...)`
    - `.slice_plot(...)`

    Use `help(ParticleGroup.plot)`, etc. for usage. 

    """