simba.Codes.Generators package

Submodules

simba.Codes.Generators.Generators module

SIMBA Beam Generator module

This module defines a class for generating a beam distribution. The beam properties, code and number of particles should be provided. The beam properties can either represent a photoinjector laser profile (if cathode=True) or beam sizes and distribution types for generating a 6D phase space.

All of the possible attributes of the class are not generic to each code, and some codes require these properties to be defined. The <code>.yaml files defined below are fed into <code>_generator_keywords dictionaries, which exclude attributes that cannot be understood by that specific code. It is noted that not all possible options are provided for the beam generators every single code; specific options can be added on request.

Other attributes have generic (human-readable) names, which are then translated to the names required for that code based on the definitions in aliases.yaml, which is read into the aliases dictionary.

These attributes can be loaded in from a .yaml file, or modified after the class is instantiated. The top-level Framework class has a generator_defaults attribute which points to a .yaml file in the <master_lattice>.Generators directory. Specific distributions can be specified therein.

Example: loading generator defaults

Prepare defaults.yaml file for generators in <master_lattice>/Generators/

defaults:
  combine_distributions: false
  species: electron
  probe_particle: true
  noise_reduction: false
  high_resolution: true
  cathode: true
  reference_position: 0
  reference_time: 0
  initial_momentum: 0
  distribution_type_pz: i
  thermal_emittance: 0.0009
  distribution_type_x: radial
  sigma_x: 0.00025
  distribution_type_y: radial
  sigma_y: 0.00025
  offset_x: 0
  offset_y: 0
laser_3ps_gaussian:
  distribution_type_z: g
  sigma_t: 0.000000000003
  gaussian_cutoff_x: 3
  gaussian_cutoff_y: 3
  gaussian_cutoff_z: 3
laser_2ps_flattop:
  distribution_type_z: p
  plateau_bunch_length: 0.000000000002
  plateau_rise_time: 0.0000000000002

Define generator in settings.def file:

generator:
  default: laser_2ps_flattop
files:
  ...

Load in generator settings

import simba.Framework as fw

framework = fw.Framework(
        master_lattice=master_lattice,
        simcodes=simcodes_location,
        directory=directory,
        generator_defaults=f"defaults.yaml"
        clean=True,
        verbose=False,
    )
framework.loadSettings("Lattices/settings.def")
framework.change_generator("GPT")
framework.generator.load_defaults("laser_3ps_gaussian")
Classes:

  • frameworkGenerator: Defines parameters to be fed into a beam generator for specific codes.

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

Bases: BaseModel

Base class for defining a beam generator. This class defines the parameters to be fed into a beam generator for specific codes. The parameters can be modified after the class is instantiated, and the defaults can be loaded in from a .yaml file. The top-level Framework class has a generator_defaults attribute which points to a .yaml file in the <master_lattice>.Generators directory. Specific distributions can be specified therein.

Example: loading generator defaults.

Prepare defaults.yaml file for generators in <master_lattice>/Generators/:

defaults:
  combine_distributions: false
  species: electron
  probe_particle: true
  noise_reduction: false
  high_resolution: true
  cathode: true
  reference_position: 0
  reference_time: 0
  initial_momentum: 0
  distribution_type_pz: i
  thermal_emittance: 0.0009
  distribution_type_x: radial
  sigma_x: 0.00025
  distribution_type_y: radial
  sigma_y: 0.00025
  offset_x: 0
  offset_y: 0

laser_3ps_gaussian:
  distribution_type_z: g
  sigma_t: 0.000000000003
  gaussian_cutoff_x: 3
  gaussian_cutoff_y: 3
  gaussian_cutoff_z: 3

laser_2ps_flattop:
  distribution_type_z: p
  plateau_bunch_length: 0.000000000002
  plateau_rise_time: 0.0000000000002

Define generator in settings.def file:

<global>:
  ...
generator:
  default: laser_2ps_flattop
files:
  ...

Load in generator settings

import simba.Framework as fw

framework = fw.Framework(
    master_lattice=master_lattice,
    simcodes=simcodes_location,
    directory=directory,
    generator_defaults=f"defaults.yaml"
    clean=True,
    verbose=False,
)
framework.loadSettings("Lattices/settings.def")
framework.change_generator("opal")
framework.generator.load_defaults("laser_3ps_gaussian")
Parameters:

  • args (Any)

  • kwargs (Any)

allowedKeyWords: List = []

Is this ever used?

apply_alias_and_multiplier(config, code)[source]

Dynamically apply alias and multiplier to fields to translate them to the required names for a specific code. Multipliers are also applied, such as converting bunch length in seconds to nanoseconds as required for ASTRA. Aliases are defined in aliases.yaml, where each code has strings to be translated.

These translated attributes are then set as new attributes to this class, with the appropriate multipliers applied.

Parameters:

  • config (Dict) – Dictionary read in from aliases.yaml

  • code (str) – Name of code to convert attributes.

Return type:

None

cathode: bool = False

Emit the beam from a cathode?

cathode_radius: float = 0.0

Radius in case of a curved, i.e. non planar cathode # TODO is this ever used?

cathode_temperature: float = 0.0

[OPAL only] Photocathode temperature [K]

charge: float = 0.0

Bunch charge

charge_sign: int = -1

Sign of charge (+1 for protons, -1 for electrons)

chirp: float | list = 0.0

Energy chirp of the beam [eV/m] or list of higher-order chirps for each particle

code: Literal['ASTRA', 'astra', 'GPT', 'gpt', 'generic', 'framework', 'simba', 'SIMBA'] = 'ASTRA'

Simulation code to be used for generating distributions

combine_distributions: bool = False

[ASTRA only] If true the input list has to be specified N_add times and N_add different distributions will be added

correlation_kinetic_energy: float = 0

Kinetic energy correlation (with what?)

correlation_px: float = 0

Horizontal momentum correlation (with what?)

correlation_py: float = 0

Vertical momentum correlation (with what?)

covariance_xxp: confloat = 0.0

Covariance of horizontal position and momentum [m-rad]

covariance_yyp: confloat = 0.0

Covariance of horizontal position and momentum [m-rad]

distribution_type_px: Literal['g', 'gaussian', '2dgaussian', 'u', 'uniform', 'r', 'radial'] = 'r'

Horizontal momentum distribution type – uniform or radial available # TODO not sure what this means or what the other options are

distribution_type_py: Literal['g', 'gaussian', '2dgaussian', 'u', 'uniform', 'r', 'radial'] = 'r'

Vertical momentum distribution type – uniform or radial available # TODO not sure what this means or what the other options are

distribution_type_pz: Literal['g', 'gaussian', '2dgaussian', 'u', 'uniform', 'r', 'radial', 'i'] = 'i'

Longitudinal momentum distribution type – not sure about options # TODO not sure what this means or what the other options are

distribution_type_x: Literal['g', 'gaussian', '2dgaussian', 'u', 'uniform', 'r', 'radial'] = 'r'

Horizontal distribution type – flattop, uniform or Gaussian available

distribution_type_y: Literal['g', 'gaussian', '2dgaussian', 'u', 'uniform', 'r', 'radial'] = 'r'

Vertical distribution type – flattop, uniform or Gaussian available

distribution_type_z: Literal['p', 'plateau', 'flattop', 'g', 'gaussian', 'i'] = 'g'

Longitudinal distribution type – flattop or Gaussian available

elementary_charge: float = 1.602176634e-19

Elementary charge [C]

emission_model: Literal['ASTRA', 'NONEQUIL'] = 'ASTRA'

[OPAL only] Photoemission model (not currently implemented)

emission_steps: int = 10000

[OPAL only] Number of emission steps

executables: Any = {}

Generator executables from Framework class

fermi_energy_ev: float = 0.0

[OPAL only] Fermi energy of photocathode [eV]

filename: str = 'generator.hdf5'

Beam distribution filename to be generated

gaussian_cutoff_px: float = 3

Cut-off for Gaussian distribution in horizontal momentum plane [sigma]

gaussian_cutoff_py: float = 3

Cut-off for Gaussian distribution in vertical momentum plane [sigma]

gaussian_cutoff_pz: float = 3

Cut-off for Gaussian distribution in longitudinal momentum plane [sigma]

gaussian_cutoff_x: float = 3

Cut-off for Gaussian distribution in horizontal direction [sigma]

gaussian_cutoff_y: float = 3

Cut-off for Gaussian distribution in vertical direction [sigma]

gaussian_cutoff_z: float = 3

Cut-off for Gaussian distribution in longitudinal direction [sigma]

generate_longitudinal_distribution()[source]

Generate a longitudinal distribution with optional chirp (nonlinear z–pz correlation).

Return type:

ndarray

generate_transverse_distribution(name)[source]

Generate a transverse distribution.

Parameters:

name (str) – Name of the distribution

Return type:

ndarray

Returns:

Samples particles according to sigma_{name}, distribution_type_{name} and

gaussian_cutoff_{name} attributes.

generator_keywords: Dict = {}

Generator keywords from Framework class

global_parameters: Dict = {}

Global parameters from Framework class

high_resolution: bool = True

[ASTRA only] High-resolution cathode emission.

image_filename: str = ''

Image file used to generate transverse beam distribution (GPT only)

initial_momentum: float = 0.0

Mean initial momentum [eV/c]

kwargs: Dict = {}

Additional arguments

laser_energy: float = 0.0

[OPAL only] Photoinjector laser energy [eV]

load_defaults(defaults)[source]

Load in defaults settings either from a key in :attr:~`generator_keywords` or with a Dict. Sets these parameters as attributes of this class.

Parameters:

defaults (Union[str, Dict]) – Default generator settings

Return type:

None

longitudinal_fields: list = []

Fields defining longitudinal beam distribution (GPT only)

longitudinal_profile: str = ''

File used to generate longitudinal beam distribution (GPT only)

max_steps: int = 1000000000

[OPAL only] Max steps for tracking

n_bin: int = 10

[OPAL only] Number of energy bins

name: str = 'generator'

Name of this generator class

noise_reduction: bool = False

[ASTRA only] If true, particle coordinates are generated quasi-randomly following a Hammersley sequence.

normalized_horizontal_emittance: float = 0.0

Normalised horizontal emittance [m-rad]

normalized_vertical_emittance: float = 0.0

Normalised vertical emittance [m-rad]

number_of_particles: int = 512

Number of particles

objectdefaults: Dict = {}

Seems not to be used

property objectname

Name of this object

offset_x: float = 0

Horizontal offset from axis [m]

offset_y: float = 0

Vertical offset from axis [m]

offset_z: float = 0

Reference beam position [m]

particle_mass: float = 9.1093837015e-31

Particle mass [kg]

property particles: int

Number of particles

Getter:

Number of particles

Setter:

Set number of particles

Return type:

int

plateau_bunch_length: float = 0.0

Flat-top bunch length [s]

plateau_fall_time: float = 0.0

Fall-time for flat-top distribution [s]

plateau_rise_distance: float = 0.0

Rise-distance for flat-top distribution [m] – deprecated?

plateau_rise_time: float = 0.0

Rise-time for flat-top distribution [s]

postProcess()[source]
probe_particle: bool = True

[ASTRA only] If true, 6 probe particles are generated

reference_time: float = 0

Reference beam time [s]

rf_frequency: float = 2998500000.0

[OPAL only] Photoinjector RF frequency [Hz] (not currently implemented)

run()[source]
sigma_kinetic_energy: float = 0

Average kinetic energy [units?]

sigma_px: float = 0.0

Horizontal beam momentum sigma [eV/c]

sigma_py: float = 0.0

Vertical beam momentum sigma [eV/c]

sigma_pz: float = 0.0

Longitudinal beam momentum sigma [eV/c]

sigma_t: float = 0.0

Longitudinal beam size [s]

sigma_x: float = 0.0

Horizontal beam sigma [m]

sigma_y: float = 0.0

Vertical beam sigma [m]

sigma_z: float = 0.0

Longitudinal beam size [m]

species: str = 'electron'

Particle type

speed_of_light: float = 299792458.0

Speed of light [m/s]

thermal_emittance: float = 0.0009

Thermal emittance of beam [um-rad/m]

property thermal_kinetic_energy: float

Thermal kinetic energy of electrons [eV] emitted from a photocathode based on thermal_emittance. See Eq. (39) of Dowell & Schmerge_

Returns:

thermal kinetic energy

tstep: float = 1e-15

[OPAL only] Time step for tracking [s]

update_species(name)[source]
Parameters:

name (str)

Return type:

None

validate_generator()
validate_longitudinal_profile()
validate_particle_mass()
work_function_ev: float = 0.0

[OPAL only] Work function of photocathode [eV]

write()[source]
poly_curve(x, coeffs)[source]
sample_2d_gaussian_with_axis_cutoffs(N, mean, cov, cutoffs)[source]

Generate N samples from 2D Gaussian with different per-axis cutoffs in whitened space. cutoffs: tuple of (cutoff_x, cutoff_y) in standard deviation units.

sample_flat_top(offset, sigma, cutoff, edge_width, size)[source]

Create a flat-top distribution centered at 0, with total half-width = cutoff * sigma, and soft edges of width edge_width * sigma

sample_gaussian(offset, sigma, cutoff, size)[source]

simba.Codes.Generators.astra module

This file generates an ASTRA beam file from the provided parameters.

It includes methods to run the ASTRA generator, write the input file, and post-process the generated beam data.

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

Bases: frameworkGenerator

A class to generate an ASTRA beam file from the provided parameters.

Parameters:

  • executables – Dictionary containing the paths to the executables.

  • global_parameters – Dictionary containing global parameters for the simulation.

  • generator_keywords – Dictionary containing keywords for the generator.

  • kwargs (Any) – Additional keyword arguments for the generator.

  • args (Any)

Variables:

  • objectname – Name of the object to be generated.

  • filename – Name of the output file.

  • thermal_kinetic_energy – Thermal kinetic energy of the particles.

  • aliases – Aliases for the parameters.

  • code – Code identifier for the generator.

  • apply_alias_and_multiplier – Method to apply aliases and multipliers to the parameters.

Lprompt: bool = False
filename: str = 'generator.txt'

Name of the output file.

postProcess()[source]

Post-process the generated ASTRA beam file to create an HDF5 beam file. This method reads the ASTRA beam file and writes it to an HDF5 format. #TODO Filenames are hardcoded for simplicity and they shouldn’t be.

run()[source]

Run the ASTRA generator to create the beam file.

write()[source]

Write the ASTRA input file to the specified directory. #TODO Filenames are hardcoded for simplicity and they shouldn’t be.

simba.Codes.Generators.gpt module

This file generates a GPT beam file from the provided parameters.

It includes methods to run the GPT generator, write the input file, and post-process the generated beam data.

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

Bases: frameworkGenerator

A class to generate a GPT beam file from the provided parameters.

Parameters:

  • executables – Dictionary containing the paths to the executables.

  • global_parameters – Dictionary containing global parameters for the simulation.

  • generator_keywords – Dictionary containing keywords for the generator.

  • kwargs (Any) – Additional keyword arguments for the generator.

  • args (Any)

Variables:

  • filename – Name of the output file.

  • code – Code identifier for the generator.

  • allowedKeyWords – List of allowed keywords for the generator.

  • generator_keywords – Keywords specific to the GPT generator.

check_xy_parameters(x, y, default)[source]

Check if the parameters x and y are set correctly. If one of them is None and the other is not, set the None parameter to the value of the other. If both are None, set both to the default value. :type x: str :param x: The first parameter to check. :type y: str :param y: The second parameter to check. :type default: str :param default: The default value to set if both parameters are None. #TODO This appears not to be used in the code, consider removing it.

Return type:

None

generate_correlated_divergences()[source]

Generate correlated divergences.

Return type:

str

Returns:

String representing x-px and y-py divergences to be applied

generate_image_name(param)[source]

Generate a name for the image file based on the provided parameter. This function expands the parameter substitution, checks if the file exists, and creates a symbolic link or copies the file to the master subdirectory. This is used for image-based distributions in the beam generation in :function:`generate_radial_distribution`.

Parameters:

param (str) – The parameter containing the image filename.

Return type:

str

Returns:

The basename of the image file.

generate_longitudinal_distribution()[source]

Generate the longitudinal distribution for the beam based on the distribution type and parameters.

If the distribution type is ‘gaussian’, it generates a command for a Gaussian distribution with the specified sigma. If the distribution type is not ‘gaussian’, it generates a command for a plateau bunch length distribution.

Returns:

A string representation of the longitudinal distribution command for the GPT input file.

generate_offset_transform()[source]

Generate the offset transform command for the beam.

This command sets the transformation of the beam in the WCS (World Coordinate System) with the specified offsets in x and y (i.e. if the beam is offset from the nominal axis).

Returns:

A string representation of the offset transform command for the GPT input file.

generate_output()[source]

Generate the output command for the GPT input file at z=0. This command sets the screen for the beam output, specifying the type and position.

Returns:

A string representation of the output command for the GPT input file.

generate_particles()[source]

Generate the basic beam parameters for the GPT input file. These include the thermal kinetic energy, charge, and number of particles. :return: A string representation of the basic beam parameters.

generate_phase_space_distribution()[source]

Generate the initial phase-space distribution for the beam.

A uniform distribution is set for z, theta, and phi. #TODO Should these be configurable parameters?

Returns:

A string representation of the initial phase-space distribution command for the GPT input file.

generate_radial_distribution()[source]

Generate the radial distribution for the beam based on the parameters provided.

This function checks the distribution type and sigma values for both x and y dimensions. If the distribution type is ‘image’, it generates a command to set the beam distribution from an image file. If the sigma values for x and y are equal and the distribution types are the same, it generates a command to set a circular distribution.

If the sigma values are different but the distribution types are the same, it generates a command to set an elliptical distribution. If the distribution types are different, it returns an empty string.

Returns:

A string representation of the radial distribution command for the GPT input file.

generate_thermal_emittance()[source]

Generate the thermal emittance for the beam based on the distribution type and sigma values.

If the distribution type is ‘image’, it returns an empty string. If the sigma values for x and y are different, it generates separate commands for x and y emittance. If the sigma values are equal, it generates a command for circular emittance.

Returns:

A string representation of the thermal emittance command for the GPT input file.

load_longitudinal_profile(v)[source]
Parameters:

v (str)

Return type:

None

postProcess()[source]

Post-process the generated beam data to create an HDF5 file.

This method reads the GPT beam file and writes it to an HDF5 format. The Z component of the beam is set to zero, and the status of the particles is initialized to -1. The output HDF5 file is named ‘laser.hdf5’ and is saved in the master subdirectory. #TODO Filenames are hardcoded for simplicity and they shouldn’t be.

run()[source]

Run the GPT generator to create the beam file.

write()[source]

Write the GPT input file with the parameters defined in the class.

Base attributes of frameworkGenerator are used to generate the input file, with the appropriate aliases and multipliers applied for the GPT code.

Returns:

None

#TODO Filenames are hardcoded for simplicity and they shouldn’t be.

simba.Codes.Generators.opal module

This file generates an OPAL beam file from the provided parameters.

It includes methods to run the OPAL generator, write the input file, and post-process the generated beam data.

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

Bases: frameworkGenerator

A class to generate an OPAL beam file from the provided parameters.

Parameters:

  • executables – Dictionary containing the paths to the executables.

  • global_parameters – Dictionary containing global parameters for the simulation.

  • generator_keywords – Dictionary containing keywords for the generator.

  • kwargs (Any) – Additional keyword arguments for the generator.

  • args (Any)

Variables:

  • filename – Name of the output file.

  • code – Code identifier for the generator.

breakstr: str = '//----------------------------------------------------------------------------'

String to indicate a new section of the generator txt file

property initial_gamma: float

Calculate the initial Lorentz factor (gamma) of the particles based on their thermal kinetic energy.

Returns:

The initial Lorentz factor (gamma) of the particles.

opalglobal: Dict = {}

Global settings for OPAL

postProcess()[source]

Convert the output from OPAL to standard HDF5 format.

#TODO filename is hardcoded and it shouldn’t be.

run()[source]

Run the OPAL generator to create the beam file. This method constructs the command to run the OPAL executable with the input file and executes it in the specified working directory. :rtype: None :return: None

write()[source]

Write the OPAL commands to an input file.

Returns:

None

Module contents