atip.simulator

Module containing an interface with the AT simulator.

Members

ATSimulator	A centralised class which makes use of AT to simulate the physics data for the copy of the AT lattice which it holds.
LatticeData	LatticeData(twiss: Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], tunes: Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], chrom: Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], emittance: Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], radint: Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]])
calculate_optics	Perform the physics calculations on the lattice.

class atip.simulator.LatticeData(twiss: numpy._typing._array_like._Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str], tunes: numpy._typing._array_like._Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str], chrom: numpy._typing._array_like._Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str], emittance: numpy._typing._array_like._Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str], radint: numpy._typing._array_like._Buffer | numpy._typing._array_like._SupportsArray[numpy.dtype[Any]] | numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]] | complex | bytes | str | numpy._typing._nested_sequence._NestedSequence[complex | bytes | str])

atip.simulator.calculate_optics(at_lattice: Lattice, refpts: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], disable_emittance: bool = False) → LatticeData

Perform the physics calculations on the lattice.

Note

We choose to use the more physically accurate find_orbit6 and linopt6 functions over their faster but less representative 4d or 2d equivalents (find_orbit4, linopt2, & linopt4), see the docstrings for those functions in PyAT for more information.

Parameters:

• at_lattice (at.lattice_object.Lattice) – AT lattice definition.

• refpts (numpy.typing.NDArray) – A boolean array specifying the points at which to calculate physics data.

• disable_emittance (bool) – whether to calculate emittance.

Returns:

The calculated lattice data.

Return type:

LatticeData

class atip.simulator.ATSimulator(at_lattice, callback=None, disable_emittance=False)

A centralised class which makes use of AT to simulate the physics data for the copy of the AT lattice which it holds. It works as follows, when a change is made to the lattice in Pytac it is added to the queue attribute of this class. When the queue has changes on it a recalculation is triggered, all the changes are applied to the lattice and then the physics data calculated. This ensures that the physics data is up to date.

Attributes

up_to_date

A flag that indicates if the physics data is up to date with all the changes made to the AT lattice.

Type:

cothread.Event

Note

To avoid errors, the physics data must be initially calculated here, during creation, otherwise it could be accidentally referenced before the _lattice_data attribute exists due to delay between class creation and the end of the first calculation in the thread.

Parameters:

• at_lattice (at.lattice_object.Lattice) – An instance of an AT lattice object.

• callback (Callable) – Optional, if passed it is called on completion of each round of physics calculations.

• disable_emittance (bool) – Whether or not to perform the beam envelope based emittance calculations.

Methods:

queue_set(func, field, value)

Add a change to the queue, to be applied when the queue is emptied.

Parameters:

• func (Callable) – The function to be called to apply the change.

• field (str) – The field to be changed.

• value (float) – The value to be set.

quit_calculation_thread(timeout=10)

Quit the calculation thread after the current loop is complete.

toggle_calculations()

Pause or unpause the physics calculations by setting or clearing the _paused flag.

Note

This does not pause the emptying of the queue.

pause_calculations()

Pause the physics calculations by setting the _paused flag.

Note

This does not pause the emptying of the queue.

unpause_calculations()

Unpause the physics calculations by clearing the _paused flag.

trigger_calculation()

Unpause the physics calculations and add a null item to the queue to trigger a recalculation.

Note

This method does not wait for the recalculation to complete, that is up to the user.

wait_for_calculations(timeout=10)

Wait until the physics calculations have taken account of all changes to the AT lattice, i.e. the physics data is fully up to date.

Parameters:

timeout (float, Optional) – The number of seconds to wait for.

Returns:

False if the timeout elapsed before the calculations concluded, else True.

Return type:

bool

get_at_element(index)

Return the AT element corresponding to the given index.

Parameters:

index (int) – The index of the AT element to return.

Returns:

The element specified by the given index.

Return type:

at.elements.Element

get_at_lattice()

Return a copy of the AT lattice object.

Returns:

A copy of the AT lattice object.

Return type:

at.lattice_object.Lattice

get_s()

Return the s position of every element in the AT lattice

Returns:

The s position of each element.

Return type:

list

get_total_bend_angle()

Return the total bending angle of all the dipoles in the AT lattice.

Returns:

The total bending angle for the AT lattice.

Return type:

float

get_total_absolute_bend_angle()

Return the total absolute bending angle of all the dipoles in the AT lattice.

Returns:

The total absolute bending angle for the AT lattice.

Return type:

float

get_energy()

Return the energy of the AT lattice. Taken from the AT attribute.

Returns:

The energy of the AT lattice.

Return type:

float

get_tune(field=None)

Return the tune for the AT lattice for the specified plane.

Note

A special consideration is made so only the fractional digits of the tune are returned.

Parameters:

field (str) – The desired field (x or y) of tune, if None return both tune dimensions.

Returns:

The x or y tune for the AT lattice.

Return type:

float

Raises:

pytac.FieldException – if the specified field is not valid for tune.

get_chromaticity(field=None)

Return the chromaticity for the AT lattice for the specified plane.

Parameters:

field (str) – The desired field (x or y) of chromaticity, if None return both chromaticity dimensions.

Returns:

The x or y chromaticity for the AT lattice.

Return type:

float

Raises:

pytac.FieldException – if the specified field is not valid for chromaticity.

get_orbit(field=None)

Return the closed orbit at each element in the AT lattice for the specified plane.

Parameters:

field (str) – The desired field (x, px, y, or py) of closed orbit, if None return whole orbit vector.

Returns:

The x, x phase, y or y phase for the AT lattice as an array of floats the length of the AT lattice.

Return type:

numpy.typing.NDArray

Raises:

pytac.FieldException – if the specified field is not valid for orbit.

get_dispersion(field=None)

Return the dispersion at every element in the AT lattice for the specified plane.

Parameters:

field (str) – The desired field (x, px, y, or py) of dispersion, if None return whole dispersion vector.

Returns:

The eta x, eta prime x, eta y or eta prime y for the AT lattice as an array of floats the length of the AT lattice.

Return type:

numpy.typing.NDArray

Raises:

pytac.FieldException – if the specified field is not valid for dispersion.

get_alpha()

Return the alpha vector at every element in the AT lattice.

Returns:

The alpha vector for each element.

Return type:

numpy.typing.NDArray

get_beta()

Return the beta vector at every element in the AT lattice.

Returns:

The beta vector for each element.

Return type:

numpy.typing.NDArray

get_mu()

Return mu at every element in the AT lattice.

Returns:

The mu array for each element.

Return type:

numpy.typing.NDArray

get_m66()

Return the 6x6 transfer matrix for every element in the AT lattice.

Returns:

The 6x6 transfer matrix for each element.

Return type:

numpy.typing.NDArray

get_emittance(field=None)

Return the emittance for the AT lattice for the specified plane.

Note

The emittance at the entrance of the AT lattice is returned as it is constant throughout the lattice, and so which element’s emittance is returned is arbitrary.

Parameters:

field (str) – The desired field (x or y) of emittance, if None return both emittance dimensions.

Returns:

The x or y emittance for the AT lattice.

Return type:

float

Raises:

pytac.FieldException – if the specified field is not valid for emittance.

get_radiation_integrals()

Return the 5 Synchrotron Integrals for the AT lattice.

Returns:

The 5 radiation integrals.

Return type:

numpy.typing.NDArray

get_momentum_compaction()

Return the linear momentum compaction factor for the AT lattice.

Returns:

The linear momentum compaction factor of the AT lattice.

Return type:

float

get_energy_spread()

Return the energy spread for the AT lattice.

Returns:

The energy spread for the AT lattice.

Return type:

float

get_energy_loss()

Return the energy loss per turn of the AT lattice.

Returns:

The energy loss of the AT lattice.

Return type:

float

get_damping_partition_numbers()

Return the damping partition numbers for the 3 normal modes.

Returns:

The damping partition numbers of the AT lattice.

Return type:

numpy.typing.NDArray

get_damping_times()

Return the damping times for the 3 normal modes. [tx, ty, tz] = (2*E0*T0)/(U0*[Jx, Jy, Jz]) [1] [1] A.Wolski; CERN Accelerator School, Advanced Accelerator Physics Course, Low Emittance Machines, Part 1: Beam Dynamics with Synchrotron Radiation; August 2013; eqn. 68

Returns:

The damping times of the AT lattice.

Return type:

numpy.typing.NDArray

get_linear_dispersion_action()

Return the Linear Dispersion Action (“curly H”) for the AT lattice.

Returns:

Curly H for the AT lattice

Return type:

float

get_horizontal_emittance()

Return the horizontal emittance for the AT lattice calculated from the radiation integrals, as opposed to the beam envelope formalism used by AT’s ohmi_envelope function.

Returns:

The horizontal (‘x’) emittance for the AT lattice.

Return type:

float