georges_core package

Subpackages

Submodules

georges_core.distribution module

Georges-core beam distribution module.

This module provides a collection of functions and classes to deal with a beam distribution. After loading or generating a distribution, methods are available to compute beam properties, such as mean, standard deviation, Twiss parameters, emittance or the beam halo.

georges_core.distribution.load_from_file(path: str = '', filename: str = '', file_format: str = 'csv') → DataFrame[source]

Load a distribution from a file

Parameters:

path (str, optional) – Path to the file. Defaults to “”.
filename (str, optional) – Name of the file. Defaults to “”.
file_format (str, optional) – Format of the file. Defaults to “csv”.

Returns:

Pandas dataframe with the distributions.

Return type:

_pd.DataFrame

georges_core.distribution.generate_from_5d_sigma_matrix(n: int, x: float = 0, px: float = 0, y: float = 0, py: float = 0, dpp: float = 0, s11: float = 0, s12: float = 0, s13: float = 0, s14: float = 0, s15: float = 0, s22: float = 0, s23: float = 0, s24: float = 0, s25: float = 0, s33: float = 0, s34: float = 0, s35: float = 0, s44: float = 0, s45: float = 0, s55: float = 0, matrix: ndarray[Any, dtype[float64]] | None = None) → ndarray[Any, dtype[float64]][source]

Parameters:

n –
x –
px –
y –
py –
dpp –
s11 –
s12 –
s13 –
s14 –
s15 –
s22 –
s23 –
s24 –
s25 –
s33 –
s34 –
s35 –
s44 –
s45 –
s55 –
matrix –

Returns:

exception georges_core.distribution.DistributionException(m: str = '')[source]

Bases: Exception

Exception raised for errors in the Beam module.

class georges_core.distribution.Distribution(distribution: DataFrame | None = None)[source]

Bases: object

Particle beam to be tracked in a beamline or accelerator model.

The internal representation is essentially a pandas DataFrame.

Initialize a beam object from various sources of particle beam distribution. :param distribution: distribution of particles to initialize the beam with. Should be pandas.DataFrame() friendly.

property distribution: DataFrame: Return a dataframe containing the beam’s particles distribution.

property dims: int: Return the dimensions of the beam’s phase-space.

property n_particles: int: Return the number of particles in the beam’s distribution.

property mean: Series: Return a dataframe containing the first order moments of each dimension.

property std: Series: Return a dataframe containing the second order moments of each dimension.

property emit: Dict[str, float]: Return the emittance of the beam in both planes

property sigma: Series: Return the sigma matrix of the beam

property covariance: Series: Return the sigma matrix of the beam

property twiss: Dict[str, float]: Return the Twiss parameters of the beam

property halo: DataFrame: Return a dataframe containing the 1st, 5th, 95th and 99th percentiles of each dimensions.

static compute_twiss(beam: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]][source]

Compute Twiss parameters of a beam From http://nicadd.niu.edu/~syphers/tutorials/analyzeTrack.html

Parameters:: beam (_np.ndarray) – beam input distribution
Returns:: An array with the Twiss parameters
Return type:: _np.array

classmethod from_csv(path: str = '', filename: str = '') → Distribution[source]

Parameters:

path (str) – Path to the csv file
filename (str) – filename

Returns:

An instance of the class with the distribution

classmethod from_parquet(path: str = '', filename: str = '') → Distribution[source]

Parameters:

path (str) – path to the parquet file
filename (str) – filename

Returns:

An instance of the class with the distribution

classmethod from_5d_sigma_matrix(n: int, x: ~pint.Quantity = <Quantity(0, 'meter')>, px: float = 0, y: ~pint.Quantity = <Quantity(0, 'meter')>, py: float = 0, dpp: float = 0, s11: ~pint.Quantity = <Quantity(0, 'meter ** 2')>, s12: float = 0, s13: float = 0, s14: float = 0, s15: float = 0, s22: float = 0, s23: float = 0, s24: float = 0, s25: float = 0, s33: ~pint.Quantity = <Quantity(0, 'meter ** 2')>, s34: float = 0, s35: float = 0, s44: float = 0, s45: float = 0, s55: float = 0, matrix: ~typing.Any | None = None) → Distribution[source]

Initialize a beam with a 5D particle distribution from a Sigma matrix. :param n: number of particles :type n: int :param x: Horizontal position [m] :type x: _Q :param px: Horizontal component momentum of unit vector :type px: float :param y: Vertical position [m] :type y: _Q :param py: Vertical component momentum of unit vector :type py: float :param dpp: Momentum spread :type dpp: float :param s11 (): :param s12 (): :param s13 (): :param s14 (): :param s15 (): :param s22 (): :param s23 (): :param s24 (): :param s25 (): :param s33 (): :param s34 (): :param s35 (): :param s44 (): :param s45 (): :param s55 (): :param matrix ():

Returns:: An instance of the class with the distribution

classmethod from_5d_multigaussian_distribution(n: int = 100000, x: ~pint.Quantity = <Quantity(0, 'meter')>, px: float = 0, y: ~pint.Quantity = <Quantity(0, 'meter')>, py: float = 0, dpp: float = 0, xrms: ~pint.Quantity = <Quantity(0, 'meter')>, pxrms: float = 0, yrms: ~pint.Quantity = <Quantity(0, 'meter')>, pyrms: float = 0, dpprms: float = 0) → Distribution[source]

Initialize a beam with a 5D particle distribution from rms quantities. :param n: number of particles :type n: int :param x: Horizontal position [m] :type x: _Q :param px (): Horizontal component momentum of unit vector :param y: Vertical position [m] :type y: _Q :param py: Vertical component momentum of unit vector :type py: float :param dpp: Momentum spread :type dpp: float :param xrms: Horizontal Gaussian sigma [m] :type xrms: _Q :param pxrms: Sigma of the horizontal component of unit momentum :type pxrms: float :param yrms: Vertical Gaussian sigma [m] :type yrms: _Q :param pyrms: Sigma of the vertical component of unit momentum :type pyrms: float :param dpprms: Relative momentum spread :type dpprms: float

Returns:: An instance of the class with the distribution

classmethod from_twiss_parameters(n: int = 100000, x: ~pint.Quantity = <Quantity(0, 'meter')>, px: float = 0, y: ~pint.Quantity = <Quantity(0, 'meter')>, py: float = 0, dpp: float = 0, betax: ~pint.Quantity = <Quantity(1, 'meter')>, alphax: float = 0, betay: ~pint.Quantity = <Quantity(1, 'meter')>, alphay: float = 0, emitx: ~pint.Quantity = <Quantity(1e-06, 'meter * radian')>, emity: ~pint.Quantity = <Quantity(1e-06, 'meter * radian')>, dispx: ~pint.Quantity = <Quantity(0, 'meter')>, dispy: ~pint.Quantity = <Quantity(0, 'meter')>, dispxp: float = 0, dispyp: float = 0, dpprms: float = 0) → Distribution[source]

Initialize a beam with a 5D particle distribution from Twiss parameters. :param n: number of particles :type n: int :param x: Horizontal position [m] :type x: _Q :param px: Horizontal component momentum of unit vector :type px: float :param y: Vertical position [m] :type y: _Q :param py: Vertical component momentum of unit vector :type py: float :param dpp: Momentum spread :type dpp: float :param betax: Horizontal beta function [m] :type betax: _Q :param alphax (): Horizontal alpha function :param betay: Vertical beta function [m] :type betay: _Q :param alphay: Vertical alpha function :type alphay: float :param emitx: Horizontal emittance [m rad] :type emitx: _Q :param emity: Vertical emittance [m rad] :type emity: _Q :param dispx: Horizontal dispersion function [m] :type dispx: _Q :param dispy: Vertical dispersion function [m] :type dispy: _Q :param dispxp: Horizontal angular dispersion function :type dispxp: float :param dispyp: Vertical angular dispersion function :type dispyp: float :param dpprms: Relative momentum spread :type dpprms: float

Returns:: An instance of the class with the distribution

georges_core.frame module

Module for handling of affine geometry transformations (rotations and translations).

This module provides support for affine geometry transformations, mainly through the Frame class. A typical use case, the one that triggered the development of this module for ::py:module Zgoubidoo, is the problem of placing a sequence with each object being placed with respect to the one preceeding it, with each object being potentially translate or rotated. In such a case, the ::py:module Frame module allows to define a reference frame for each object being placed, with the reference frame of the newly created object using the reference frame of the previous object as a reference frame for its own positioning. The translations and rotations of the object are thus trivially expressed in its own reference frame. The ::py:module Frame module then allows to query the coordinates and rotation information of the object with respect to any other reference frame in the chain of transformations. In particular, the coordinates of the origin of a frame along with its orientation in space, can be obtained with respect to a global (absolute) reference frame.

Example

example TODO

exception georges_core.frame.FrameException(m: str = '')[source]

Bases: Exception

Exception raised for errors in the Frame module.

class georges_core.frame.Frame(parent: Frame | None = None, reference: Frame | None = None)[source]

Bases: object

A Frame object represents a reference frame for affine geometry transformations (rotations and translations). It has full support for transformation chaining through the notion of ‘parent frame’ and is able to provide rotation angles and translation offsets with respect to any parent among the linked list of parents.

Additionnally Frames are unit-aware through the use of ‘pint quantities’. The internal representations use the ‘quaternion-numpy’ module with the base units being radians and meters. This is transparent to the public interface which can use arbitrary units for the representations of lengths and angles.

Frame handles quaternion rotations via quaternion-numpy: https://github.com/moble/quaternion .

>>> f1 = Frame()
>>> f1.translate_y(10 * _ureg.cm) 
<georges_core.frame.Frame object at 0x...>
>>> f2 = Frame(parent=f1)
>>> f2.parent == f1
True
>>> f2.translate_x(1 * _ureg.cm) 
<georges_core.frame.Frame object at 0x...>
>>> f2.get_origin(f1)
[<Quantity(0.01, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.o == f2.origin == f2.get_origin(None)
True

Initialize a Frame with respect to a parent frame. If no parent is provided the newly created frame is considered to be a global reference frame. The frame is create with no rotation or translate with respect to its parent frame.

Parameters:

parent – parent frame, if None then the frame itself is considered as a global reference frame.
reference – reference frame, all quantities are provided by default with respect to this frame.
function. (This allows to use the properties easily but can be modified on a case-by-case basis for each) –
creation. (Alternatively the reference frame can be modified after the object) –

__eq__(o: Frame) → bool[source]

Equality comparison with another Frame.

Parameters:: o – other frame to be compared with
Returns:: True if the two frames are strictly equal (same parent and equal rotation and origin) else otherwise

Example

>>> f1 = Frame()
>>> f2 = Frame()
>>> f1.rotate_x(10 * _ureg.degree) 
<georges_core.frame.Frame object at 0x...>
>>> f1 == f2
False
>>> f2.rotate_x(10 * _ureg.degree) 
<georges_core.frame.Frame object at 0x...>
>>> f1 == f2
True

property parent: Frame | None

Provides the parent frame.

Returns:: parent frame, None in case the frame is a global reference frame.

Examples

>>> f1 = Frame()
>>> f1.parent is None
True
>>> f2 = Frame(parent=f1)
>>> f2.parent == f1
True

The ‘parent’ property can also be set:

>>> f1 = Frame()
>>> f1.parent is None
True
>>> f2 = Frame()
>>> f2.parent is None
True
>>> f2.parent = f1
>>> f2.parent is f1
True
>>> f2.parent == f1
True
>>> f2.parent = None
>>> f2.parent is None
True

property reference: Frame | None

Provides the reference frame with respect to which the quantities will be provided. None if not set.

Returns:: a frame serving as reference frame for the current frame (None if not set)

Examples

>>> f1 = Frame(parent=None, reference=None)
>>> f1.reference is None
True
>>> f2 = Frame(parent=f1, reference=f1)
>>> f2.reference is f1
True
>>> f2.reference == f1
True
>>> f2.reference = None
>>> f2.reference is None
True

get_quaternion(ref: Frame | None = None) → quaternion[source]

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters:: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns:: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

property quaternion: quaternion

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters:: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns:: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

property q: quaternion

Provides the quaternion representation of the rotation of the frame with respect to another reference frame.

Parameters:: ref – reference frame with respect to which the rotation quaternion is returned. If None then the rotation is provided with respect to the current reference frame.
Returns:: the quaternion representing the rotation with respect to a given reference frame.

Examples

>>> f1 = Frame().rotate_z(20 * _ureg.degree)
>>> f1.get_quaternion()
quaternion(0.984807753012208, 0, 0, 0.17364817766693)
>>> f2 = Frame(f1)
>>> f2.rotate_x(10 * _ureg.degree).get_quaternion() 
quaternion(0.981060..., 0.085831..., 0.015134..., 0.172987...)
>>> f2.get_quaternion(f1) 
quaternion(0.996194..., 0.087155..., 0, 0)

property o_: ndarray

Provides the offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters:: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the current reference frame.

Retunrs:: the offset (numpy array, no units) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_origin()
array([0.1, 0. , 0. ])
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_origin()
array([0.1, 1. , 0. ])
>>> f2._get_origin(f1)
array([0., 1., 0.])

property origin_: ndarray

Provides the offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters:: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the current reference frame.

Retunrs:: the offset (numpy array, no units) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_origin()
array([0.1, 0. , 0. ])
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_origin()
array([0.1, 1. , 0. ])
>>> f2._get_origin(f1)
array([0., 1., 0.])

get_origin(ref: Frame | None = None) → List[Quantity][source]

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters:: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns:: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

property o: List[Quantity]

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters:: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns:: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

property origin: List[Quantity]

Offset of the frame with respect to a reference frame.

Provides the offset representing the translation of the frame with respect to another reference frame. This method supports units and returns pint quantities with dimensions of [LENGTH].

Parameters:: ref – reference frame with respect to which the origin is returned. If None then the translation is provided with respect to the global reference frame.
Returns:: the offset (list of quantities with dimensions of [LENGTH]) representing the translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(0.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_origin()
[<Quantity(0.1, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(0.0, 'meter')>, <Quantity(1.0, 'meter')>, <Quantity(0.0, 'meter')>]

property x_: float

X axis offset with respect to a reference frame (internal units).

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Parameters:

ref – reference frame with respect to which the origin is returned.
frame. (If None then the translation is provided with respect to the current reference) –

Returns:

the X axis offset (float, no units) representing the X axis translation with respect to a given reference frame.

Examples

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1._get_x()
0.1
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2._get_x()
0.1
>>> f2._get_x(f1)
0.0

get_x(ref: Frame | None = None) → Quantity[source]

X axis offset with respect to a reference frame.

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_x()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_x()
<Quantity(0.1, 'meter')>
>>> f2.get_x(f1)
<Quantity(0.0, 'meter')>

Parameters:: ref – reference frame with respect to which the origin is returned.

If None then the translation is provided with respect to the current reference frame.

Returns:: the X axis offset (with units, pint quantity) representing the X axis translation with respect to a given reference frame.

property x: Quantity

X axis offset with respect to a reference frame.

Provides the X axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_x(10 * _ureg.cm)
>>> f1.get_x()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_y(100 * _ureg.cm)
>>> f2.get_x()
<Quantity(0.1, 'meter')>
>>> f2.get_x(f1)
<Quantity(0.0, 'meter')>

Parameters:: ref – reference frame with respect to which the origin is returned.

If None then the translation is provided with respect to the current reference frame.

Returns:: the X axis offset (with units, pint quantity) representing the X axis translation with respect to a given reference frame.

property y_: float

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1._get_y()
0.1
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2._get_y()
0.1
>>> f2._get_y(f1)
0.0

Parameters:

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
frame. (with respect to the current reference) –

Returns:

the Y axis offset (float, no units) representing the Y axis translation with respect to a given reference frame.

get_y(ref: Frame | None = None) → Quantity[source]

Y axis offset with respect to a reference frame.

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

Examples

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1.get_y()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_y()
<Quantity(0.1, 'meter')>
>>> f2.get_y(f1)
<Quantity(0.0, 'meter')>

Parameters:

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
frame. (with respect to the current reference) –

Returns:

the Y axis offset (with units, pint quantity) representing the Y axis translation with respect to

a given reference frame.

property y: Quantity

Y axis offset with respect to a reference frame.

Provides the Y axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

Examples

>>> f1 = Frame().translate_y(10 * _ureg.cm)
>>> f1.get_y()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_y()
<Quantity(0.1, 'meter')>
>>> f2.get_y(f1)
<Quantity(0.0, 'meter')>

Parameters:

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
frame. (with respect to the current reference) –

Returns:

the Y axis offset (with units, pint quantity) representing the Y axis translation with respect to

a given reference frame.

property z_: float

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works in the internal unit representation of the class Frame.

Examples

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1._get_z()
0.1
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2._get_z()
0.1
>>> f2._get_z(f1)
0.0

Parameters:

ref – reference frame with respect to which the origin is returned.
frame. (If None then the translation is provided with respect to the current reference) –

Returns:

the Z axis offset (float, no units) representing the Z axis translation with respect to a given reference frame.

get_z(ref: Frame | None = None) → Quantity[source]

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1.get_z()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_z()
<Quantity(0.1, 'meter')>
>>> f2.get_z(f1)
<Quantity(0.0, 'meter')>

Parameters:

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
frame. (with respect to the current reference) –

Returns:

the Z axis offset (with units, pint quantity) representing the Z axis translation with respect to a given reference frame.

property z: Quantity

Provides the Z axis offset representing the translation of the frame with respect to another reference frame. This method works with full support of pint units.

>>> f1 = Frame().translate_z(10 * _ureg.cm)
>>> f1.get_z()
<Quantity(0.1, 'meter')>
>>> f2 = Frame(f1).translate_x(100 * _ureg.cm)
>>> f2.get_z()
<Quantity(0.1, 'meter')>
>>> f2.get_z(f1)
<Quantity(0.0, 'meter')>

Parameters:

ref – reference frame with respect to which the origin is returned. If None then the translation is provided
frame. (with respect to the current reference) –

Returns:

the Z axis offset (with units, pint quantity) representing the Z axis translation with respect to a given reference frame.

get_rotation_matrix(ref: Frame | None = None) → ndarray[source]

Provides the rotation matrix representation of the quaternion with respect to another reference frame.

Example

>>> f1 = Frame().rotate_x(10 * _ureg.degree).get_rotation_matrix()
>>> f1 
array([[ 1.        ,  0.        ,  0.        ],
[ 0.        ,  0.98480775, -0.17364818],
[ 0.        ,  0.17364818,  0.98480775]])

Parameters:: ref – reference frame with respect to which the rotation matrix is returned
Returns:: the rotation matrix representation of the quaternion

get_euler_angles(ref: Frame | None = None) → ndarray[source]

Parameters:: ref –

Returns:

get_rotation_vector(ref: Frame | None = None) → ndarray[source]

Parameters:: ref –

Returns:

get_angles(ref: ~georges_core.frame.Frame | None = None, units: ~pint.Unit = <Unit('radian')>) → List[Quantity][source]

Examples

>>> f1 = Frame() # TODO

Parameters:

ref –
units –

Returns:

property angles: List[Quantity]

Examples

>>> f1 = Frame() # TODO

Parameters:

ref –
units –

Returns:

get_tx(ref: Frame | None = None) → Quantity[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

property tx: Quantity

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

get_ty(ref: Frame | None = None) → Quantity[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

property ty: Quantity

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

get_tz(ref: Frame | None = None) → Quantity[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

property tz: Quantity

Examples

>>> f1 = Frame() # TODO

Parameters:: ref –

Returns:

__mul__(q: quaternion) → Frame[source]

Provide a simple way to rotate the Frame in a generic way, by multiplying directly with a quaternion.

Examples

>>> f = Frame()
>>> q = _quaternion.from_rotation_vector([0, 0, 0.5])
>>> (f * q).tx
<Quantity(-0.5, 'radian')>

Parameters:: q – a quaternion by which the frame is multiplied representing the rotation
Returns:: the rotated frame (in place), allows method chaining

rotate(angles: List[Quantity]) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: angles –
Returns:: the rotated frame (in place), allows method chaining

rotate_x(angle: Quantity) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: angle –

Returns:

rotate_y(angle: Quantity) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: angle –

Returns:

rotate_z(angle: Quantity) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: angle –

Returns:

rotate_axis(axis: str, angle: float) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:

axis –
angle –

Returns:

__add__(offset: List[Quantity]) → Frame[source]

Provide a simple way to translate the Frame in a generic way, by adding an offset directly. This method is unit-aware and the offset must be provided as a list of pint Quantities.

Examples

>>> f = Frame()
>>> offset = [1.0 * _ureg.cm, 2.0 * _ureg.cm, 3.0 * _ureg.cm]
>>> (f + offset).x
<Quantity(0.01, 'meter')>
>>> (f + offset).y
<Quantity(0.04, 'meter')>
>>> (f + offset).z
<Quantity(0.09, 'meter')>

Parameters:: offset – a list representing the offset (elements of the list must be quantities of dimension [LENGTH])
Returns:: the translated frame (in place)

translate(offset: List[Quantity]) → Frame[source]

Translates the origin of the Frame with respect to the parent reference frame. The translations are extrinsic (done with respect to the axes of the parent frame).

Examples

>>> f1 = Frame()
>>> f1.translate([1.0 * _ureg.meter, 2.0 * _ureg.meter, 3.0 * _ureg.meter]).o
[<Quantity(1.0, 'meter')>, <Quantity(2.0, 'meter')>, <Quantity(3.0, 'meter')>]
>>> f2 = Frame(parent=f1)
>>> f2.translate([1.0 * _ureg.meter, 2.0 * _ureg.meter, -3.0 * _ureg.meter]).o
[<Quantity(2.0, 'meter')>, <Quantity(4.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(1.0, 'meter')>, <Quantity(2.0, 'meter')>, <Quantity(-3.0, 'meter')>]
>>> f2.rotate_x(180 * _ureg.degree).o
[<Quantity(2.0, 'meter')>, <Quantity(4.0, 'meter')>, <Quantity(0.0, 'meter')>]
>>> f2.get_origin(f1)
[<Quantity(1.0, 'meter')>, <Quantity(2.0, 'meter')>, <Quantity(-3.0, 'meter')>]

Parameters:: offset – a list representing the offset (elements of the list must be quantities of dimension [LENGTH])
Returns:: the translated frame (in place), allows method chaining

translate_x(offset: Quantity) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: offset –

Returns:

translate_y(offset: Quantity) → Frame[source]

Examples

>>> f1 = Frame() # TODO

Parameters:: offset –

Returns:

translate_z(offset: Quantity) → Frame[source]

Example

>>> f1 = Frame() # TODO

Parameters:: offset –
Returns:: the translated frame (in place)

translate_axis(axis: str, offset: Quantity) → Frame[source]

Example

>>> f1 = Frame() # TODO

Parameters:

axis –
offset –

Returns:

the translated frame (in place)

reset() → Frame[source]

Reset the frame.

Reset the frame (rotation and translation) with respect to the parent; the frame is thus equivalent to its parent frame.

Examples

>>> f1 = Frame().rotate_x(1 * _ureg.radian)
>>> f1.get_angles() 
[<Quantity(0.0, 'radian')>, <Quantity(1.0..., 'radian')>, <Quantity(1.0..., 'radian')>]
>>> f1.reset().get_angles()
[<Quantity(0.0, 'radian')>, <Quantity(0.0, 'radian')>, <Quantity(0.0, 'radian')>]

Returns:: the reseted frame itself (to allow method chaining).

class georges_core.frame.FrameFrenet(parent: Frame | None = None, reference: Frame | None = None)[source]

Bases: Frame

Initialize a Frame with respect to a parent frame. If no parent is provided the newly created frame is considered to be a global reference frame. The frame is create with no rotation or translate with respect to its parent frame.

Parameters:

parent – parent frame, if None then the frame itself is considered as a global reference frame.
reference – reference frame, all quantities are provided by default with respect to this frame.
function. (This allows to use the properties easily but can be modified on a case-by-case basis for each) –
creation. (Alternatively the reference frame can be modified after the object) –

georges_core.geometry module

TODO

class georges_core.geometry.Intersections(lines1, line2)[source]

Bases: object

validate_format(lines1, line2)[source]

property u

property v

property w

property parallels

property not_parallels

property coincidents

property not_coincidents

property parameters_at_intersections

property intersects_ray_segment

property intersections

class georges_core.geometry.ReferenceTrajectory(points: Points)[source]

Bases: object

Initialized with an array of 6D data points (x, y, z, t, p, s)

frenet_frames()[source]: Returns an array of frenet frames (representation of planes)

property data

class georges_core.geometry.Trajectories(lines: ndarray)[source]: Bases: Lines

class georges_core.geometry.Points(points: ndarray)[source]

Bases: Primitives

Parameters:: points –

number_points()[source]

property x

property y

property z

property t

property p

property s

property coordinates

georges_core.geometry.project_on_reference(ref: ReferenceTrajectory, trajectories: list)[source]: Projects a set of NT trajectories on a reference trajectory (array of points of length NR). For each trajectory (array of points of length NI), computes the coordinates associated with each data point of the reference trajectory (so it returns an array of NT projected trajectories, each of length NR).

georges_core.kinematics module

Georges-core relativistic’ physics module.

This module provides a collection of functions and classes to deal with relativistic physics computations. This mainly concerns conversions between kinematic quantities. Full support for units (via pint) is provided. Additionnally, a helper class (Kinematics) provides automatic construction and conversion of kinematics quantities.

Examples

>>> Kinematics(230 *_ureg.MeV) 

Proton
(.etot) Total energy: 1168.2720299999999 megaelectronvolt
(.ekin) Kinetic energy: 230 megaelectronvolt
(.momentum) Momentum: 696.0640299570144 megaelectronvolt_per_c
(.brho): Magnetic rigidity: 2.321819896553311 meter * tesla
(.range): Range in water (protons only): 32.9424672323197 centimeter
(.pv): Relativistic pv: 414.71945005821954 megaelectronvolt
(.beta): Relativistic beta: 0.5958064663732595
(.gamma): Relativistic gamma: 1.2451314678963625

exception georges_core.kinematics.KinematicsException(m: str = '')[source]

Bases: Exception

Exception raised for errors in the Kinematics module.

class georges_core.kinematics.Kinematics(q: Union[float, _Q], particle: _ParticuleType = <class 'georges_core.particles.Proton'>, kinetic: Optional[bool] = None)[source]

Bases: object

TODO

Parameters:

q –
particle –
kinetic –

property particule: _ParticuleType: Associated particle type.

to(quantity: str) → float | Quantity[source]

Parameters:: quantity –

Returns:

to_range(magnitude: bool = False) → float | Quantity[source]

Parameters:: magnitude –

Returns:

property range: float | Quantity: TODO

property range_: float | _Q: TODO

to_ekin(magnitude: bool = False) → float | Quantity[source]

Parameters:: magnitude –

Returns:

property ekin: float | Quantity: TODO

property ekin_: float | _Q: TODO

to_etot(magnitude: bool = False) → float | Quantity[source]

Parameters:: magnitude –

Returns:

property etot: float | Quantity: TODO

property etot_: float | _Q: TODO

to_momentum(magnitude: bool = False) → float | Quantity[source]

Parameters:: magnitude –

Returns:

property momentum: float | Quantity: Provides the momentum.

property momentum_: float | _Q: Provides the momentum (magnitude only).

to_brho(magnitude: bool = False) → float | Quantity[source]

Parameters:: magnitude –

Returns:

property brho: float | Quantity: Provides brho.

property brho_: float | _Q: Provides brho (magnitude only).

to_pv() → Quantity[source]: Returns:

property pv: Quantity: Provides pv.

to_beta() → float[source]: Returns:

property beta: float: Provides beta.

to_gamma() → float[source]: Returns:

property gamma: float: Provides gamma.

georges_core.kinematics.etot_to_ekin(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to kinetic energy.

>>> etot_to_ekin(1168 * _ureg.MeV)
<Quantity(229.72797, 'megaelectronvolt')>

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Kinetic energy of the particle

georges_core.kinematics.etot_to_momentum(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to momentum.

>>> etot_to_momentum(1168 * _ureg.MeV).to('MeV_c')
<Quantity(695.607359, 'megaelectronvolt_per_c')>

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Momentum of the particle

georges_core.kinematics.etot_to_brho(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to magnetic rigidity (brho).

>>> etot_to_brho(1168 * _ureg.MeV).to('T m')
<Quantity(2.32029661, 'meter * tesla')>

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Magnetic rigidity of the particle

georges_core.kinematics.etot_to_range(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to proton range in water; following IEC-60601.

>>> etot_to_range(1168 * _ureg.MeV).to('cm')
<Quantity(32.8760931, 'centimeter')>

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Proton range in water

georges_core.kinematics.etot_to_pv(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to relativistic pv.

>>> etot_to_pv(1168 * _ureg.MeV)
<Quantity(414.271916, 'megaelectronvolt')>

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.etot_to_beta(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to relativistic beta.

>>> etot_to_beta(1168 * _ureg.MeV)
0.595554245611312

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle

georges_core.kinematics.etot_to_gamma(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts total energy to relativistic gamma.

>>> etot_to_beta(1168 * _ureg.MeV)
0.595554245611312

Parameters:

e – Total energy of the particle
particle – the particle type (default: proton)

Returns:

Relativistic gamma of the particle

georges_core.kinematics.ekin_to_etot(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts kinetic energy to total energy

>>> ekin_to_etot(100 * _ureg.MeV)
<Quantity(1038.27203, 'megaelectronvolt')>

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Total energy of the particle

georges_core.kinematics.ekin_to_momentum(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts kinetic energy to momentum

>>> ekin_to_momentum(100 * _ureg.MeV).to('MeV_c')
<Quantity(444.583407, 'megaelectronvolt_per_c')>
>>> ekin_to_momentum(230 * _ureg.MeV).to('MeV_c')
<Quantity(696.06403, 'megaelectronvolt_per_c')>

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Momentum of the particle

georges_core.kinematics.ekin_to_brho(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts kinetic energy to magnetic rigidity (brho).

>>> ekin_to_brho(100 * _ureg.MeV).to('T m')
<Quantity(1.48297076, 'meter * tesla')>
>>> ekin_to_brho(230 * _ureg.MeV).to('T m')
<Quantity(2.3218199, 'meter * tesla')>

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Magnetic rigidity of the particle

georges_core.kinematics.ekin_to_range(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts kinetic energy to proton range in water; following IEC-60601.

>>> ekin_to_range(100 * _ureg.MeV).to('cm')
<Quantity(7.72696361, 'centimeter')>
>>> ekin_to_range(230 * _ureg.MeV).to('cm')
<Quantity(32.9424672, 'centimeter')>

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Proton range in water

georges_core.kinematics.ekin_to_pv(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts kinetic energy to relativistic pv.

>>> ekin_to_pv(230 * _ureg.MeV)
<Quantity(414.71945, 'megaelectronvolt')>

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.ekin_to_beta(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts the kinetic energy to relativistic beta.

>>> ekin_to_beta(230 * _ureg.MeV)
0.5958064663732595

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle

georges_core.kinematics.ekin_to_gamma(e: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts the kinetic energy to relativistic gamma.

>>> ekin_to_gamma(230 * _ureg.MeV)
1.2451314678963625

Parameters:

e – kinetic energy
particle – the particle type (default: proton)

Returns:

Relativistic gamma of the particle

georges_core.kinematics.momentum_to_etot(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts momentum to total energy.

>>> momentum_to_etot(100 * _ureg.MeV_c).to('MeV')
<Quantity(943.585927, 'megaelectronvolt')>

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Total energy of the particle

georges_core.kinematics.momentum_to_ekin(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts momentum to kinetic energy.

>>> momentum_to_ekin(100 * _ureg.MeV_c).to('MeV')
<Quantity(5.31389734, 'megaelectronvolt')>

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Kinetic energy of the particle

georges_core.kinematics.momentum_to_brho(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts momentum to magnetic rigidity (brho).

>>> momentum_to_brho(100 * _ureg.MeV_c).to('tesla * meter')
<Quantity(0.333564126, 'meter * tesla')>

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Magnetic rigidity of the particle

georges_core.kinematics.momentum_to_range(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts momentum to proton range in water; following IEC-60601.

>>> momentum_to_range(696 * _ureg.MeV_c).to('cm')
<Quantity(32.9331561, 'centimeter')>

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Range of the particle

georges_core.kinematics.momentum_to_pv(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts momentum to relativistic pv.

>>> momentum_to_pv(696 * _ureg.MeV_c).to('megaelectronvolt')
<Quantity(414.656695, 'megaelectronvolt')>

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.momentum_to_beta(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts momentum to relativistic beta.

>>> momentum_to_beta(696 * _ureg.MeV_c)
0.5957711130629324

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle

georges_core.kinematics.momentum_to_gamma(p: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts momentum to relativistic gamma.

>>> momentum_to_gamma(696 * _ureg.MeV_c)
1.2450908098255749

Parameters:

p – relativistic momentum
particle – the particle type (default: proton)

Returns:

Relativistic gamma of the particle

georges_core.kinematics.brho_to_etot(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts magnetic rigidity (brho) to total energy.

>>> brho_to_etot(3 * _ureg.tesla * _ureg.meter).to('MeV')
<Quantity(1299.70532, 'megaelectronvolt')>

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

the total energy of the particle.

georges_core.kinematics.brho_to_ekin(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts magnetic rigidity (brho) to kinetic energy.

>>> brho_to_ekin(3 * _ureg.tesla * _ureg.meter).to('MeV')
<Quantity(361.433288, 'megaelectronvolt')>

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

the kinetic energy of the particle.

georges_core.kinematics.brho_to_momentum(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts magnetic rigidity (brho) to momentum.

>>> brho_to_momentum(3 * _ureg.T * _ureg.m).to('MeV/c')
<Quantity(899.377291, 'megaelectronvolt / speed_of_light')>

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

the momentum of the particle.

georges_core.kinematics.brho_to_range(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts magnetic rigidity (brho) to range.

>>> brho_to_range(3 * _ureg.tesla * _ureg.meter).to('cm')
<Quantity(70.5706415, 'centimeter')>

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

the range of the particle.

georges_core.kinematics.brho_to_pv(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts magnetic rigidity (brho) to relativistic pv.

>>> brho_to_pv(3 * _ureg.tesla * _ureg.meter).to('MeV')
<Quantity(622.356084, 'megaelectronvolt')>

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.brho_to_beta(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts magnetic rigidity (brho) to relativistic beta.

>>> brho_to_beta(3 * _ureg.tesla * _ureg.meter)
0.6919855437534259

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle

georges_core.kinematics.brho_to_gamma(brho: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → float[source]

Converts magnetic rigidity (brho) to relativistic gamma.

>>> brho_to_gamma(3 * _ureg.tesla * _ureg.meter)
1.385211619719756

Parameters:

brho – the magnetic rigidity
particle – the particle type (default: proton)

Returns:

Relativistic gamma of the particle

georges_core.kinematics.range_to_etot(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Examples

>>> range_to_etot(32 * _ureg.cm).to('MeV')
<Quantity(1164.40114, 'megaelectronvolt')>

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

Total energy of the particle.

georges_core.kinematics.range_to_ekin(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to kinetic energy following IEC60601.

Examples

>>> range_to_ekin(32 * _ureg.cm).to('MeV')
<Quantity(226.129112, 'megaelectronvolt')>

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

the kinetic energy of the particle.

georges_core.kinematics.range_to_momentum(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to momentum.

>>> range_to_momentum(32 * _ureg.cm).to('MeV / c')
<Quantity(689.5474, 'megaelectronvolt / speed_of_light')>

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

the momentum of the particle.

georges_core.kinematics.range_to_brho(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to magnetic rigidity (brho).

>>> range_to_brho(32 * _ureg.cm).to('T m')
<Quantity(2.30008276, 'meter * tesla')>

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

The magnetic rigidity (brho) of the particle.

georges_core.kinematics.range_to_pv(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to relativistic pv.

>>> range_to_pv(32 * _ureg.cm).to('MeV')
<Quantity(408.343482, 'megaelectronvolt')>

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

the relativistic pv of the particle.

georges_core.kinematics.range_to_beta(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to relativistic beta.

>>> range_to_beta(32 * _ureg.cm)
0.5921905906552516

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle.

georges_core.kinematics.range_to_gamma(r: _Q, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts proton range in water to relativistic beta.

>>> range_to_gamma(32 * _ureg.cm)
1.2410059178641932

Parameters:

r – proton range in water
particle – the particle type (default: proton)

Returns:

Relativistic beta of the particle.

georges_core.kinematics.beta_to_etot(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to total energy.

>>> beta_to_etot(0.3).to('MeV')
<Quantity(983.576342, 'megaelectronvolt')>
>>> beta_to_etot(0.9).to('MeV')
<Quantity(2152.54366, 'megaelectronvolt')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Total energy of the particle

georges_core.kinematics.beta_to_ekin(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to kinetic energy.

>>> beta_to_ekin(0.3).to('MeV')
<Quantity(45.3043118, 'megaelectronvolt')>
>>> beta_to_ekin(0.9).to('MeV')
<Quantity(1214.27163, 'megaelectronvolt')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Kinetic energy of the particle

georges_core.kinematics.beta_to_momentum(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to momentum.

>>> beta_to_momentum(0.3).to('MeV/c')
<Quantity(295.072903, 'megaelectronvolt / speed_of_light')>
>>> beta_to_momentum(0.9).to('MeV/c')
<Quantity(1937.2893, 'megaelectronvolt / speed_of_light')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Momentum of the particle

georges_core.kinematics.beta_to_brho(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to magnetic rigidity.

>>> beta_to_brho(0.3).to('T m')
<Quantity(0.984257348, 'meter * tesla')>
>>> beta_to_brho(0.9).to('T m')
<Quantity(6.46210211, 'meter * tesla')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Magnetic rigidity of the particle

georges_core.kinematics.beta_to_range(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to range.

>>> beta_to_range(0.3).to('cm')
<Quantity(1.83016632, 'centimeter')>
>>> beta_to_range(0.9).to('cm')
<Quantity(503.718206, 'centimeter')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Range of the particle

georges_core.kinematics.beta_to_pv(beta: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic beta to relativistic pv.

>>> beta_to_pv(0.15).to('MeV')
<Quantity(21.3527053, 'megaelectronvolt')>
>>> beta_to_pv(0.9).to('MeV')
<Quantity(1743.56037, 'megaelectronvolt')>

Parameters:

beta – relativistic beta
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.beta_to_gamma(beta: float, **_) → float[source]

Converts relativistic beta to relativistic gamma.

>>> beta_to_gamma(0.5)
1.1547005383792517
>>> beta_to_gamma(0.9)
2.294157338705618

Parameters:: beta – relativistic beta
Returns:: Relativistic gamma of the particle

georges_core.kinematics.gamma_to_etot(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to total energy.

>>> gamma_to_etot(1.5).to('MeV')
<Quantity(1407.40804, 'megaelectronvolt')>
>>> gamma_to_etot(1.2).to("MeV")
<Quantity(1125.92644, 'megaelectronvolt')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Total energy of the particle

georges_core.kinematics.gamma_to_ekin(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to kinetic energy.

>>> gamma_to_ekin(100.0).to('MeV')
<Quantity(92888.931, 'megaelectronvolt')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Kinetic energy of the particle

georges_core.kinematics.gamma_to_momentum(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to momentum.

>>> gamma_to_momentum(100.0).to('MeV/c')
<Quantity(93822.5115, 'megaelectronvolt / speed_of_light')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Momentum of the particle

georges_core.kinematics.gamma_to_brho(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to magnetic rigidity.

>>> gamma_to_brho(100.0).to('T m')
<Quantity(312.95824, 'meter * tesla')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Magnetic rigidity of the particle

georges_core.kinematics.gamma_to_range(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to range (protons only).

>>> gamma_to_range(100.0)
<Quantity(277356.143, 'centimeter')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Range of the particle

georges_core.kinematics.gamma_to_pv(gamma: float, particle: _ParticuleType = <class 'georges_core.particles.Proton'>) → _Q[source]

Converts relativistic gamma to relativistic pv.

>>> gamma_to_pv(100.0)
<Quantity(93817.8203, 'megaelectronvolt_per_c2 * speed_of_light ** 2')>

Parameters:

gamma – relativistic gamma
particle – the particle type (default: proton)

Returns:

Relativistic pv of the particle

georges_core.kinematics.gamma_to_beta(gamma: float, **_: Any) → float[source]

Converts relativistic gamma to relativistic beta.

>>> gamma_to_beta(1.5)
0.7453559924999299

Parameters:: gamma – relativistic gamma
Returns:: Relativistic beta of the particle

georges_core.particles module

TODO

class georges_core.particles.ParticuleType[source]: Bases: type

class georges_core.particles.Particule[source]

Bases: object

Particle characteristics.

M: Quantity | None = None

Q: Quantity | None = None

G: float | None = None

tau: float | None = None

property mass: Quantity | None: Mass of the particle.

property charge: Quantity | None: Charge of the particle.

property lifetime: float | None: Lifetime constant of the particle.

property gyro: float | None: Gyromagnetic factor of the particle.

property name: str: Gyromagnetic factor of the particle.

class georges_core.particles.Electron[source]

Bases: Particule

An electron.

M: Quantity | None = <Quantity(0.510998946, 'megaelectronvolt_per_c2')>

Q: Quantity | None = <Quantity(-1.60217662e-19, 'coulomb')>

G: float | None = -2.0011596521810997

name = 'e-'

class georges_core.particles.Proton[source]

Bases: Particule

A proton.

M: Quantity | None = <Quantity(938.27203, 'megaelectronvolt_per_c2')>

Q: Quantity | None = <Quantity(1.60217649e-19, 'coulomb')>

G: float | None = 1.7928473505000002

name = 'Proton'

class georges_core.particles.AntiMuon[source]

Bases: Particule

An anti-muon particle.

M: Quantity | None = <Quantity(1.88353163e-28, 'kilogram')>

Q: Quantity | None = <Quantity(1.60217663e-19, 'coulomb')>

G: float | None = -2.0011659209

tau: float | None = <Quantity(2.197029e-06, 'second')>

georges_core.particles.Posmuon: alias of AntiMuon

georges_core.patchable module

Patchable elements module.

class georges_core.patchable.Patchable[source]

Bases: object

Patchable elements are beamline elements that affect the placement of the reference frame.

A default implementation of the placement methods is provided for subclasses. It only places the entrance frame at the location of the placement frame and all other frames are set to the entrance frame (‘point-like’ element).

Initializes a un-patched patchable element.

place(frame: Frame) → None[source]

Place the element with a reference frame.

All the frames of the element are reset and the entrance frame is then placed with respect to the reference frame.

Parameters:: frame – the reference frame for the placement of the entrance frame.

clear_placement() → None[source]: Clears all the frames.

property length: Quantity

Length of the element.

Returns:: the length of the element with units.

property entry: Frame | None

Entrance frame.

Returns:: the frame of the entrance of the element.

property entry_patched: Frame

Entrance patched frame.

Returns:: the frame of the entrance of the element with the patch applied.

property exit: Frame

Exit frame.

Returns:: the frame of the exit of the element.

property exit_patched: Frame

Exit patched frame.

Returns:: the frame of the exit of the element with the patch applied.

property center: Frame

Center frame.

Returns:: the frame of the center of the element.

property reference_trajectory: DataFrame: Returns:

georges_core.twiss module

Module for the computation of Twiss parametrizations from transfer matrices.

The standard uncoupled Twiss parametrization (including off-momentum effects, aka. dispersion) is the default option. Additional formalisms for the parametrization of fully coupled transfer matrices are also available (Teng, Ripken, etc.).

class georges_core.twiss.ParametrizationType[source]: Bases: type

class georges_core.twiss.Parametrization[source]

Bases: object

compute_canonical_transformation_matrix(matrix_row: Series, kin: Kinematics) → Series[source]

static compute_canonical_transfer_matrices(matrix_row: Series, matrix_rs1: ndarray) → Series[source]

static compute_one_turn_transfer_matrix(matrix_row: Series, mat_tot: ndarray) → Series[source]

compute_eigenvectors(matrix_row: Series) → Series[source]

compute_orderded_turned_normalized_eigenvectors()[source]

static phase_unrolling(phi, s)[source]: TODO

static compute_turned_eigvec(v1: ndarray, v1_: ndarray, plane: int = 1)[source]

class georges_core.twiss.Twiss(twiss_init: BetaBlock | None = None, with_phase_unrolling: bool = True)[source]

Bases: Parametrization

Parameters:

twiss_init – the initial values for the Twiss computation (if None, periodic conditions are assumed and the
matrix). (Twiss parameters are computed from the transfer) –
with_phase_unrolling – TODO

__call__(matrix: DataFrame, end: int | str = -1) → DataFrame[source]

Uses a step-by-step transfer matrix to compute the Twiss parameters (uncoupled). The phase advance and the determinants of the jacobians are computed as well.

Parameters:: matrix – the input step-by-step transfer matrix
Returns:: the same DataFrame as the input, but with added columns for the computed quantities.

static compute_alpha_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1) → Series[source]

Computes the Twiss alpha values at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the alpha values should be computed
twiss – the initial Twiss values
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the alpha values computed at all steps of the input step-by-step transfer matrix

static compute_beta_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1, strict: bool = False) → Series[source]

Computes the Twiss beta values at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the beta values should be computed
twiss – the initial Twiss values
plane – an integer representing the block (1 or 2)
strict – flag to activate the strict mode: checks and ensures that all computed beta are positive

Returns:

a Pandas Series with the beta values computed at all steps of the input step-by-step transfer matrix

static compute_gamma_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1) → Series[source]

Computes the Twiss gamma values at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the beta values should be computed
twiss – the initial Twiss values
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the gamma values computed at all steps of the input step-by-step transfer matrix

static compute_mu_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1) → Series[source]

Computes the phase advance values at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the beta values should be computed
twiss – the initial Twiss values
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the phase advance computed at all steps of the input step-by-step transfer matrix

static compute_jacobian_from_matrix(m: DataFrame, plane: int = 1) → Series[source]

Computes the jacobian of the 2x2 transfer matrix (useful to verify the simplecticity).

Parameters:

m – the step-by-step transfer matrix for which the jacobians should be computed
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the jacobian computed at all steps of the input step-by-step transfer matrix

static compute_dispersion_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1) → Series[source]

Computes the dispersion function at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the dispersion function should be computed
twiss – initial values for the Twiss parameters
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the dispersion function computed at all steps of the input step-by-step transfer matrix

static compute_dispersion_prime_from_matrix(m: DataFrame, twiss: BetaBlock, plane: int = 1) → Series[source]

Computes the dispersion prime function at every steps of the input step-by-step transfer matrix.

Parameters:

m – the step-by-step transfer matrix for which the dispersion prime function should be computed
twiss – initial values for the Twiss parameters
plane – an integer representing the block (1 or 2)

Returns:

a Pandas Series with the dispersion prime function computed at all steps of the input step-by-step transfer matrix

Example:

static compute_periodic_twiss(matrix: DataFrame, end: int | str = -1) → BetaBlock[source]

Compute twiss parameters from a transfer matrix which is assumed to be a periodic transfer matrix.

Parameters:

matrix – the (periodic) transfer matrix
end –

Returns:

a Series object with the values of the periodic Twiss parameters.

class georges_core.twiss.Parzen(twiss_init: BetaBlock | None = None, with_phase_unrolling: bool = True)[source]

Bases: Parametrization

Parameters:

twiss_init – the initial values for the Twiss computation (if None, periodic conditions are assumed and the
matrix). (Twiss parameters are computed from the transfer) –
with_phase_unrolling – TODO

__call__(matrix: DataFrame, tracks: DataFrame, kin: Kinematics) → DataFrame[source]

Uses a step-by-step transfer matrix to compute the generalized Twiss parameters (coupled motions) with the parametrization of Edwards and Teng using the method with eigenvectors presented in the paper of G. Parzen. The phase advances are computed as well.

Parameters:

matrix – the input step-by-step transfer matrix
tracks – tracks_global for the centered particle ‘O’ of the BeamTwiss
kin – Kinematics object

Returns:

the same DataFrame as the matrix input DataFrame, but with added columns for the computed quantities.

get_initial_parametrisation(twiss_init: BetaBlock | None) → Tuple[source]

static compute_normalized_eigenvectors(v1, v1_)[source]

static compute_orderded_complex_conjugate_vectors_pair(phi_1: float, phi_2: float, eigvec: ndarray, plane: int = 1)[source]

compute_orderded_turned_normalized_eigenvectors(eigvec: ndarray | None = None, lambda1_0: float | None = None, eigvals: ndarray | None = None)[source]

compute_eigenvectors_from_initial_eigvecs(matrix_row: Series, x_1: ndarray) → Series[source]

static compute_parametrisation_from_eigenvectors(matrix_row: Series) → Series[source]

static compute_decoupling_matrix_from_eigenvectors(matrix_row: Series) → Series[source]

static compute_decoupled_transfer_matrix(matrix_row: Series, r_decoupling_0: ndarray) → Series[source]

static compute_phase_advances(matrix_row: Series, eigvec_init) → Series[source]

static check_tunes(matrix_row: Series)[source]

georges_core.twiss.EdwardsTengTwiss: alias of Parzen

class georges_core.twiss.LebedevTwiss(twiss_init: BetaBlock | None = None, with_phase_unrolling: bool = True, all_periodic: bool = False)[source]

Bases: Parametrization

Parameters:

twiss_init – the initial values for the Twiss computation (if None, periodic conditions are assumed and the
matrix). (Twiss parameters are computed from the transfer) –
with_phase_unrolling – TODO

__call__(matrix: DataFrame, tracks: DataFrame, kin: Kinematics) → DataFrame[source]

Uses a step-by-step transfer matrix to compute the generalized Twiss parameters (coupled motions) with the parametrization of V.A. Lebedev and S.A Bogacz. The phase advances are computed as well.

Parameters:

matrix – the input step-by-step transfer matrix
tracks – tracks_global for the centered particle ‘O’ of the BeamTwiss

Returns:

the same DataFrame as the matrix input DataFrame, but with added columns for the computed quantities.

get_initial_normalisation_matix(twiss_init: BetaBlock | None) → ndarray[source]

static compute_turned_normalisation_matrix(matrix_row: Series, v1: ndarray) → Series[source]

static compute_normalisation_matrix_from_V2_turned(matrix_row: Series) → Series[source]

static compute_normalized_eigenvectors(v1, v1_)[source]

compute_orderded_turned_normalized_eigenvectors(eigvec: ndarray | None = None, lambda1_0: float | None = None, eigvals: ndarray | None = None)[source]

static compute_normalisation_matrix_from_eigenvectors(matrix_row: Series) → Series[source]

static compute_parametrisation_from_normalisation_matrix(matrix_row: Series) → Series[source]

static compute_phase_advances(matrix_row: Series, initial_normalisation_matrix) → Series[source]

static compute_phase_advances_bis(matrix_row: Series, eigvec_init) → Series[source]

compute_periodic_LebedevTwiss(matrix: DataFrame, tracks: DataFrame, kin: Kinematics) → DataFrame[source]

Parameters:

matrix – the input step-by-step transfer matrix
tracks – tracks_global for the centered particle ‘O’ of the BeamTwiss

Returns:

the same DataFrame as the matrix input DataFrame, but with added columns for the computed quantities.

class georges_core.twiss.RipkenTwiss[source]: Bases: Parametrization

class georges_core.twiss.WolskiTwiss[source]: Bases: Parametrization

georges_core.units module

Manipulation of physical quantities (with units, etc.).

See https://pint.readthedocs.io/en/latest/

georges_core.utils module

Utility functions.

georges_core.utils.fortran_float(input_string: str) → float[source]

Returns a float of the input string, just like float(input_string), but allowing for Fortran’s string formatting to screw it up when you have very small numbers (like 0.31674-103 instead of 0.31674E-103 ).

georges_core package

Subpackages

Submodules

georges_core.distribution module

georges_core.frame module

georges_core.geometry module

georges_core.kinematics module

georges_core.particles module

georges_core.patchable module

georges_core.twiss module

georges_core.units module

georges_core.utils module

Module contents