piol.gicosyelements module

Inheritance diagram

API reference

class piol.gicosyelements.GICOSYDipole(refple, ftype, rho0, phi0, G0, directionAngle=0, nvalues=None, eps_entrance=0.0, curv_entrance=0.0, eps_exit=0.0, curv_exit=0.0, ff_entrance=1, ff_exit=1, order=1, maxSAdvance=0.2, collimator=None, name='Dipole', description='')

Bases: piol.gicosyelements.GICOSYElement

Dipole element

Interact with a magnetic or electric dipole to bend a beam with the given radius and deflection angle.

Parameters

• refple (ReferenceParticle) – Reference particle for the element creation.

• ftype ({'electric', 'magnetic'}) – String representing the type of dipole.

• rho0 (float) – Radius of curvature in m.

• phi0 (float) – Angle of deflection in degrees.

• G0 (float) – Half gap of dipole in m.

• directionAngle (float) – Defines the direction of B field in degrees in the dipole in the optical axis xyz-coordinate system at the entrance. 0 deg corresponds the case that B field is towards positive y-direction and positive particles are to be bend towards negative x-axis (by Lorentz force), 90 deg <-> B field towards positive x-axis and positive particles are to be bend upwords, 180 deg <-> B-field to neg. y-axis and positive particles are to be bend towards positive x-axis.

• nvalues (list of floats, optional) – Field indices of the multipole expansion.

• eps_entrance (float, optional) – Entrance angle of the field boundary in degree (default zero).

• curv_entrance (float, optional) – Entrance field curvature relative to rho0 (default zero).

• eps_exit (float, optional) – Exit angle of the field boundary in degree (default zero).

• curv_exit (float, optional) – Exit field curvature relative to rho0 (default zero).

• ff_entrance (int, optional) – Fringe fields table number to use for entrance. Use zero for no fringe field.

• ff_exit (int, optional) – Fringe fields table number to use for exit. Use zero for no fringe field.

• order (int, optional) – Order of the transfermatrix. Defaults to 1.

• maxSAdvance (float, optional) – Maximal advance along the s axis in m. Defaults to 0.2

• collimator (float or tuple, optional) – Collimator parameters if one is used.

• name (string, optional) – Name given to the element.

• description (string, optional) – Description of the element, currently not used.

collimator

Collimator used in the element.

Type

Collimator or None

parts

Number of times the transfer matrix is to be used.

Type

int

Notes

The most parameters are saved in the parameters dictionary. A warning will be issued in the logger if the collimator is larger than it should be.

field(kind)

Return the field strength within the element.

Parameters

kind ({'magnetic' , 'electric'}) – String to select field type.

Returns

Field strength within the element.

Return type

float

height()

Calculate the height of the element.

Returns

float

Return type

Height of the element.

length()

Calculate the length of the element.

Returns

float

Return type

Length of the element.

opticalAxisExit()

Returns the exiting optical axis.

Returns the coordinate transformation from the entrance plane to the exit plane. The returned value is a tuple (r,x,y), where r (vector) is a translation from entrance optical axis origin to exit optical axis origin; x and y are unit vectors defining the exit plane coordinate system. The z-axis is the cross product of x and y, and points towards positive optical axis.

plot(ax, view, s)

Plot the element

Plots a representation of the element using the plotter interface in a cross section view. Defaults to plotting nothing.

Parameters

• ax (Axis) – Axis instance to plot on

• view (str) – String describing which viewpoint to draw on. Must be known to the Plotter.

• s (float) – Starting distance along the optical axis for element start.

rebuild()

Rebuilds element if any of its parameters have been modified.

Defaults to doing nothing.

class piol.gicosyelements.GICOSYDrift(refple, dl, order=1, maxSAdvance=0.2, collimator=None, name='Drift length', description='')

Bases: piol.gicosyelements.GICOSYElement

Drift element

Transports the beam through a length without electromagnetic interactions.

Parameters

• refple (ReferenceParticle) – Reference particle for the element creation.

• dl (float) – Drift length of the element in m.

• order (int) – Order of the transfermatrix.

• maxSAdvance (float) – Maximal advance along the s axis in m.

• collimator (float or tuple, optional) – Collimator parameters if one is used.

• name (string, optional) – Name given to the element.

• description (string, optional) – Description of the element, currently not used.

collimator

Collimator used in the element.

Type

Collimator or None

parts

Number of times the transfer matrix is to be used.

Type

int

Notes

The reference particle, the order and the driftlength are saved in the parameters.

height()

Calculate the height of the element.

Returns

float

Return type

Height of the element.

length()

Calculate the length of the element.

Returns

float

Return type

Length of the element.

plot(ax, view, s)

Plot the element

Plots a representation of the element using the plotter interface in a cross section view. Defaults to plotting nothing.

Parameters

• ax (Axis) – Axis instance to plot on

• view (str) – String describing which viewpoint to draw on. Must be known to the Plotter.

• s (float) – Starting distance along the optical axis for element start.

rebuild()

Rebuilds element if any of its parameters have been modified.

Defaults to doing nothing.

class piol.gicosyelements.GICOSYElement(refple, name='', description='')

Bases: piol.elements.TMElement

Base class for all transfer matrix elements using gicosy.

extractMatrices(energy, mass, charge, commands, order=1)

Runs external GICOSY program and extracts matrices.

Overwrites the fringe field data file GICOSYFF.DAT if marked with tag ‘PIOL’, otherwise rises an exception.

Parameters

• energy (float) – energy of a reference particle in eV

• mass (float) – mass of a reference particle in atomic mass units

• charge (float) – charge of a reference particle in units of elementary charge

• commands (list of str) – list of lines to be inserted into GICOSY.DAT file without a semicolon

• order (int) – order of transfer matrices

Returns

Return type

list of TransferMatrix objects.

getTransferMatrix()

Returns full transfer matrix of the system.

If full transfer matrix is found already then returning it. Otherwise calculating it.

transfer(driver)

Transfers the particles saved in the driver through the element.

Parameters

driver (Driver) – Driver of the system

class piol.gicosyelements.GICOSYQuadrupole(refple, ftype, dl, field, G0, ff_entrance=1, ff_exit=1, order=1, maxSAdvance=0.2, collimator=None, name='Quadrupole', description='')

Bases: piol.gicosyelements.GICOSYElement

Quadrupole element

Interact with a magnetic or electric quadrupole with the given field over the given length.

Parameters

• refple (ReferenceParticle) – Reference particle for the element creation.

• ftype ({'electric', 'magnetic'}) – String representing the type of quadrupole.

• dl (float) – Drift length of the element in m.

• field (float) – Voltage (V) or magnetic (T) field to be used in the quadrupole.

• G0 (float) – Aperture radius of the quad in m.

• ff_entrance (int, optional) – Fringe fields table number to use for entrance. Use zero for no fringe field.

• ff_exit (int, optional) – Fringe fields table number to use for exit. Use zero for no fringe field.

• order (int) – Order of the transfermatrix.

• maxSAdvance (float) – Maximal advance along the s axis in m.

• collimator (float or tuple, optional) – Collimator parameters if one is used.

• name (string, optional) – Name given to the element.

• description (string, optional) – Description of the element, currently not used.

collimator

Collimator used in the element.

Type

Collimator or None

parts

Number of times the transfer matrix is to be used.

Type

int

Notes

The reference particle, the order and the driftlength are saved in the parameters. A warning will be sent into the logger if the aperture is larger that it should be.

field(kind)

Return the field strength within the element.

Parameters

kind ({'magnetic' , 'electric'}) – String to select field type.

Returns

Field strength within the element.

Return type

float

height()

Calculate the height of the element.

Returns

float

Return type

Height of the element.

length()

Calculate the length of the element.

Returns

float

Return type

Length of the element.

plot(ax, view, s)

Plot the element

Plots a representation of the element using the plotter interface in a cross section view. Defaults to plotting nothing.

Parameters

• ax (Axis) – Axis instance to plot on

• view (str) – String describing which viewpoint to draw on. Must be known to the Plotter.

• s (float) – Starting distance along the optical axis for element start.

rebuild()

Rebuilds element if any of its parameters have been modified.

Defaults to doing nothing.

piol.gicosyelements.setFringeField(element, tableno, params, force=False)

Set fringe field for an element type and table number tableno.

By default PIOL uses a built-in standard table for fringe fields. Currently the fringe field data contains mostly nonsense.

Parameters

• element (str) – The element type. One of {‘MS’, ‘ES’, ‘MQ’, ‘EQ’}.

• tableno (int) – The table number to set. Valid table numbers are from 1 to 9.

• params (array-like) – An array of polynomial coefficients describing the fringe field with the Enge model. Lowest order first. Maximum of 11th order polynomial is supported.

• force (boolean) – Forces the overwriting of the GICOSYFF.DAT file. Defaults to ‘False’.

piol.gicosyelements.setGICOSYPath(path)

Define the path to the GICOSY installation directory.

The GICOSYElement and the derived classes require access to GICOSY program for producing the elements matrices. This function is used to set the path to the GICOSY program manually. The access to GICOSY can be defined with this function or by default the PIOL searches for the presence of either a GICOSYPATH environment variable or a folder with ‘gicosy’ in the PATH. If neither can be found, an exception will be raised.

Parameters

path (str) – Path to GICOSY installation directory.

piol.gicosyelements.writeFringeFields(force=False)

Writes the GICOSYFF.DAT fringe field data file.

Overwrites the fringe field data file GICOSYFF.DAT if marked with tag ‘* PIOL’, otherwise rises an exception. Overwriting the fringe field data file can be forced by setting force=True.