simba.Modules.Fields package

Submodules

simba.Modules.Fields.FieldParameter module

class FieldParameter(*args, **kwargs)[source]

Bases: BaseModel

FieldParameter class to represent a field parameter with a name and an optional value.

name(str)

The name of the field parameter.

value(UnitValue | None)

The value of the field parameter, which can be a UnitValue or None.

Parameters:

  • args (Any)

  • kwargs (Any)

name: str
value: UnitValue | ndarray | list | None = None

simba.Modules.Fields.astra module

generate_astra_field_data(self)[source]

Generate the field data in a format that is suitable for ASTRA, based on the field object provided. The field_type parameter determines the format of the file. See the ASTRA manual for more details.

A warning is raised if the field type is not supported (perhaps elevate to a NotImplementedError?

Parameters:

self (field) – The field object

Returns:

The formatted field data.

Return type:

np.ndarray

read_astra_field_file(self, filename, field_type, cavity_type=None, frequency=None)[source]

Read a field file from ASTRA format and convert it into a field object (self). Certain parameters must be included, particularly for RF cavities.

See the ASTRA manual for more details.

Parameters:

  • self (field) – The field object to be updated.

  • filename (str) – The path to the ASTRA field file

  • field_type (str) – The name of the field, see allowed_fields

  • cavity_type (str, optional) – The type of RF cavity, see allowed_cavities

  • frequency (float, optional) – The frequency of the RF cavity.

Return type:

None

Raises:

  • ValueError: – if the cavity field_type contains the string Electro and cavity_type is not provided

  • ValueError: – if the cavity field_type contains the string Electro and frequency is not provided

  • NotImplementedError: – if a given field_type is not implemented

write_astra_field_file(self)[source]

Write the field data in an ASTRA-compatible format, based on the field object provided. The absolute location of the file to be written is generated using _output_filename(), which is parsed from the Master Lattice.

Parameters:

self (field) – The field object

Returns:

The converted filename

Return type:

str

simba.Modules.Fields.gdf module

read_gdf_field_file(self, filename, field_type, cavity_type=None, frequency=None, normalize_b=True)[source]

Read a GDF field file and convert it into a simba.Modules.Fields.field object

Parameters:

  • self (field) – The field object to be updated.

  • filename (str) – The path to the GDF field file

  • field_type (str) – The name of the field, see allowed_fields

  • cavity_type (str, optional) – The type of RF cavity, see allowed_cavities

  • frequency (float, optional) – The frequency of the RF cavity.

  • normalize_b (bool, optional) – Normalize Bx and By with respect to Bz (True by default)

Return type:

None

Raises:

  • ValueError: – if the cavity field_type contains the string Electro and cavity_type is not provided

  • ValueError: – if the cavity field_type contains the string Electro and frequency is not provided

  • NotImplementedError: – if a given field_type is not implemented

union(blocks)[source]

Update the field data into a format compatible for easyGDF

Parameters:

blocks (List[Dict]) – The field parameters, keyed by name

Returns:

A list of easyGDF-compatible dictionaries

Return type:

List

write_gdf_field_file(self)[source]

Generate the field data in a format that is suitable for GPT, based on the field object provided. This is then written to a GDF file. The field_type parameter determines the format of the file.

A warning is raised if the field type is not supported (perhaps elevate to a NotImplementedError?

Parameters:

self (field) – The field object

Returns:

The name of the GDF field file.

Return type:

str

simba.Modules.Fields.hdf5 module

read_HDF5_field_file(self, filename)[source]

Read an HDF5 field file and convert it into a simba.Modules.Fields.field object

Parameters:

  • self (field) – The field object.

  • filename (str) – The path to the HDF5 field file

Returns:

The name of the HDF5 file

Return type:

str

Raises:

  • KeyError: – if the cavity_type attribute is not in :attr:`~simba.Modules.Fields.allowed_cavities

  • KeyError: – if cavity_type==TravellingWave and all the required attributes are not defined in the file; see :attr:`~simba.Modules.Fields.tw_required_attrs

  • Warning: – if a given parameter in the field is not normalised to 1.0

write_HDF5_field_file(self)[source]

Write the simba.Modules.Fields.field object to an HDF5 file. All of the attributes of the class are read, and if they are defined and in the correct format, they are written to the file.

Parameters:

self (field) – The field object to be saved.

Returns:

The name of the HDF5 file

Return type:

str

simba.Modules.Fields.opal module

read_opal_field_file(self, filename, field_type, cavity_type=None, frequency=None)[source]

Read an OPAL field file and convert it into a simba.Modules.Fields.field object

Parameters:

  • self (field) – The field object to be updated.

  • filename (str) – The path to the OPAL field file

  • field_type (str) – The name of the field, see allowed_fields

  • cavity_type (str, optional) – The type of RF cavity, see allowed_cavities

  • frequency (float, optional) – The frequency of the RF cavity.

Return type:

None

Raises:

  • ValueError: – if the cavity field_type contains the string Electro and cavity_type is not provided

  • ValueError: – if the cavity field_type contains the string Electro and frequency is not provided

  • NotImplementedError: – if a given field_type is not implemented

write_opal_field_file(self, frequency=None, radius=None, fourier=100, orientation=None)[source]

Generate the field data in a format that is suitable for OPAL, based on the field object provided.

See the OPAL manual for more details.

This is then written to a text file. The field_type parameter determines the format of the file.

A warning is raised if the field type is not supported (perhaps elevate to a NotImplementedError?

Parameters:

  • self (field) – The field object

  • frequency (float | None) – The frequency of the field

  • radius (float | None) – The radius of the field, for 1D axially symmetric fields; defaults to 0.1

  • fourier (int = 100) – Number of fourier coefficients

  • orientation (str | None) – Orientation of the field (for 2D)

Returns:

The name of the field file. Will return None if required parameters for certain fields are not provided.

Return type:

str | None

Raises:

  • Warning: – if too many or not enough fourier components are provided; will default to 1/100

  • Warning: – if the magnet radius is not provided; will default to 0.1

  • Warning: – if the RF frequency, radius or orientation is not provided for 1DElectroDynamic or 2DElectrodynamic, return None

  • Warning: – if trying to use wakefields; these are tricky to get working with OPAL

  • Warning: – if a given field_type is not supported.

simba.Modules.Fields.sdds module

read_SDDS_field_file(self, filename, field_type)[source]

Read an SDDS field file and convert it into a simba.Modules.Fields.field object. Only works for wakefield files.

Parameters:

  • self (field) – The field object to be updated.

  • filename (str) – The path to the SDDS field file

  • field_type (str) – The name of the field, see allowed_fields

Return type:

None

Raises:

NotImplementedError: – if a given field_type is not implemented

write_SDDS_field_file(self, sddsindex=0, ascii=False)[source]

Generate the field data in a format that is suitable for SDDS, based on the field object provided. This is then written to an SDDS file. The field_type parameter determines the format of the file.

A warning is raised if the field type is not supported (perhaps elevate to a NotImplementedError?

Parameters:

  • self (field) – The field object

  • sddsindex (int) – Must be provided for SddsFile class

  • ascii (bool, optional) – Convert to ascii?

Returns:

The name of the SDDS field file.

Return type:

str

Module contents

Simframe Fields Module

This module defines the base class and utilities for representing electromagnetic fields, including RF structures, wakefields and magnets.

Functions are provided to read in existing files, and to write them in the format required for specific codes.

Classes:

name and a UnitValue associated with it.

class field(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Base class for representing electromagnetic fields, including RF structures, wakefields, and magnets. This class provides methods to read and write field files in various formats, including ASTRA, SDDS, GDF, and OPAL. It also includes properties for accessing field parameters such as position, electric and magnetic fields, and wakefields. The class supports validation of field types and parameters, and allows for the initialization of field objects with specific attributes such as filename, field type, frequency, and cavity type.

Br: FieldParameter = None

Radial magnetic field component.

Bx: FieldParameter = None

Magnetic field component in the X direction.

By: FieldParameter = None

Magnetic field component in the Y direction.

Bz: FieldParameter = None

Magnetic field component in the Z direction.

Er: FieldParameter = None

Radial electric field component.

Ex: FieldParameter = None

Electric field component in the X direction.

Ey: FieldParameter = None

Electric field component in the Y direction.

Ez: FieldParameter = None

Electric field component in the Z direction.

G: FieldParameter = None

Magnetic gradient.

Wr: FieldParameter = None

Radial wakefield component.

Wx: FieldParameter = None

Wakefield component in the X direction.

Wy: FieldParameter = None

Wakefield component in the Y direction.

Wz: FieldParameter = None

Wakefield component in the Z direction.

cavity_type: Optional[Literal['StandingWave', 'TravellingWave']] = None

Type of the cavity, e.g., ‘StandingWave’, ‘TravellingWave’.

end_cell_z: float | None = None

Ending position of the cell in the Z direction, required for TravellingWave cavities.

field_type: Optional[Literal['1DElectroStatic', '1DMagnetoStatic', '1DElectroDynamic', '2DElectroStatic', '2DMagnetoStatic', '2DElectroDynamic', '3DElectroStatic', '3DMagnetoStatic', '3DElectroDynamic', 'LongitudinalWake', 'TransverseWake', '3DWake', '1DQuadrupole']] = None

Type of the field, e.g., ‘1DElectroStatic’, ‘1DMagnetoStatic’, etc.

filename: str | None = None

Filename of the field file.

fourier: int = 100

Number of Fourier modes for the field, default is 100.

frequency: float | int64 | None = None

Frequency of the field, if applicable.

get_field_data(code)[source]

Generate field data in a format suitable for the specified code. This method supports generating field data for ASTRA and Ocelot. If the field file has not been read in, it raises a warning and returns None.

Parameters:

code (str:) – The code for which the field data is to be generated. Supported codes include ‘astra’ and ‘ocelot’.

Returns:

The generated field data in the format required by the specified code, or None if the field file has not been read.

Return type:

np.ndarray | None

length: int | None = None

Length of the field, if applicable.

mode_denominator: float | None = None

Denominator for the mode of the TravellingWave cavity. For TW linacs in ASTRA, the mode is 2π mode_numerator / mode_denominator

mode_numerator: float | None = None

Numerator for the mode of the TravellingWave cavity. For TW linacs in ASTRA, the mode is 2π mode_numerator / mode_denominator

n_cells: int | float | None = None

Number of cells in the field, if applicable.

norm: float = 1.0

Normalization factor for the field.

orientation: str | None = None

Orientation of the field, e.g., ‘horizontal’, ‘vertical’, etc.

origin_code: str | None = None

Code that generated the field, e.g., ‘ASTRA’, ‘SDDS’, etc.

r: FieldParameter = None

Radial position or coordinate of the field.

radius: float | None = None

Radius of the field, if applicable, defaults TO 10cm in write_opal_field_file.

read: bool = False

Flag indicating whether the field file has been read.

read_field_file(filename, field_type=None, cavity_type=None, frequency=None, normalize_b=True, **kwargs)[source]

Read a field file and populate the field parameters based on the file type. This method supports various file formats including HDF5, ASTRA, SDDS, GDF, and OPAL.

Parameters:

  • filename (str) – The path to the field file to be read.

  • field_type (fieldtype | None) – The type of the field, e.g., ‘1DElectroStatic’, ‘1DMagnetoStatic’, etc.

  • cavity_type (cavitytype | None) – The type of the cavity, e.g., ‘StandingWave’, ‘TravellingWave’.

  • frequency (float | None) – The frequency of the field, if applicable.

  • normalize_b (bool) – Normalize Bx and By with respect to Bz (True by default)

Returns:

The method modifies the field object in place, populating its parameters based on the file content.

Return type:

None

reset_dicts()[source]

Reset the field parameters to their default values.

Return type:

None

start_cell_z: float | None = None

Starting position of the cell in the Z direction, required for TravellingWave cavities.

t: FieldParameter = None

Time parameter of the field.

property t_values: List[float] | None

Returns the time values of the field. If the Z parameter is set and time is not, it calculates time based on Z and speed of light.

Returns:

A list of time values if available, otherwise None.

Return type:

List[float] | None

validate_fields(values)
write_field_file(code, location=None)[source]

Write the field data to a file in the format required by the specified code. This method supports writing field data for ASTRA, SDDS, GDF, and OPAL. If the field file has not been read in, it raises a warning and returns None. If a location is provided, it uses that as the base directory; otherwise, it defaults to the directory of the current field file.

Parameters:

  • code (str:) – The code for which the field data is to be written. Supported codes include ‘astra’, ‘sdds’, ‘opal’, and ‘gdf’.

  • location (str | None:) – Optional; if provided, it specifies the directory where the output file will be saved.

Returns:

The path to the written field file, or None if the field file has not been read.

Return type:

str | None

x: FieldParameter = None

X position or coordinate of the field.

y: FieldParameter = None

Y position or coordinate of the field.

z: FieldParameter = None

Z position or coordinate of the field.

property z_values: List[float] | None

Returns the Z values of the field. If the time parameter is set and Z is not, it calculates Z based on the time and speed of light.

Returns:

A list of Z values if available, otherwise None.

Return type:

List[float] | None