Genesis 4 Main Input

genesis.version4.MainInput

MainInput(namelists=None, *, filename=None)

Bases: BaseModel

A Genesis 4 main input configuration file.

Attributes:

Name	Type	Description
namelists	list of NameList	Elements contained in the lattice.
filename	Path or None	The filename from which this was loaded.

Source code in genesis/version4/input/core.py

def __init__(
    self,
    namelists: Optional[List[AnyNameList]] = None,
    *,
    filename: Optional[pathlib.Path] = None,
) -> None:
    if namelists is None:
        namelists = []
    super().__init__(namelists=namelists, filename=filename)

Attributes

genesis.version4.MainInput.alter_field property

alter_field

Get a single AlterField instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.alter_fields property

alter_fields

List of all AlterField instances.

genesis.version4.MainInput.alter_setup property

alter_setup

Get a single AlterSetup instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.alter_setups property

alter_setups

List of all AlterSetup instances.

genesis.version4.MainInput.beam property

beam

Get a single Beam instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.beams property

beams

List of all Beam instances.

genesis.version4.MainInput.by_namelist property

by_namelist

Get namelists organized by their class.

genesis.version4.MainInput.efield property

efield

Get a single Efield instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.efields property

efields

List of all Efield instances.

genesis.version4.MainInput.field property

field

Get a single Field instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.fields property

fields

List of all Field instances.

genesis.version4.MainInput.import_beam property

import_beam

Get a single ImportBeam instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.import_beams property

import_beams

List of all ImportBeam instances.

genesis.version4.MainInput.import_distribution property

import_distribution

Get a single ImportDistribution instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.import_distributions property

import_distributions

List of all ImportDistribution instances.

genesis.version4.MainInput.import_field property

import_field

Get a single ImportField instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.import_fields property

import_fields

List of all ImportField instances.

genesis.version4.MainInput.import_transformation property

import_transformation

Get a single ImportTransformation instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.import_transformations property

import_transformations

List of all ImportTransformation instances.

genesis.version4.MainInput.lattice property

lattice

Get a single Lattice instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.lattices property

lattices

List of all Lattice instances.

genesis.version4.MainInput.profile_array property

profile_array

Get a single ProfileArray instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_arrays property

profile_arrays

List of all ProfileArray instances.

genesis.version4.MainInput.profile_const property

profile_const

Get a single ProfileConst instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_consts property

profile_consts

List of all ProfileConst instances.

genesis.version4.MainInput.profile_file property

profile_file

Get a single ProfileFile instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_file_multi property

profile_file_multi

Get a single ProfileFileMulti instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_file_multis property

profile_file_multis

List of all ProfileFileMulti instances.

genesis.version4.MainInput.profile_files property

profile_files

List of all ProfileFile instances.

genesis.version4.MainInput.profile_gauss property

profile_gauss

Get a single ProfileGauss instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_gausses property

profile_gausses

List of all ProfileGauss instances.

genesis.version4.MainInput.profile_polynom property

profile_polynom

Get a single ProfilePolynom instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_polynoms property

profile_polynoms

List of all ProfilePolynom instances.

genesis.version4.MainInput.profile_step property

profile_step

Get a single ProfileStep instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.profile_steps property

profile_steps

List of all ProfileStep instances.

genesis.version4.MainInput.sequence_const property

sequence_const

Get a single SequenceConst instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_consts property

sequence_consts

List of all SequenceConst instances.

genesis.version4.MainInput.sequence_filelist property

sequence_filelist

Get a single SequenceFilelist instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_filelists property

sequence_filelists

List of all SequenceFilelist instances.

genesis.version4.MainInput.sequence_list property

sequence_list

Get a single SequenceList instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_lists property

sequence_lists

List of all SequenceList instances.

genesis.version4.MainInput.sequence_polynom property

sequence_polynom

Get a single SequencePolynom instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_polynoms property

sequence_polynoms

List of all SequencePolynom instances.

genesis.version4.MainInput.sequence_power property

sequence_power

Get a single SequencePower instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_powers property

sequence_powers

List of all SequencePower instances.

genesis.version4.MainInput.sequence_random property

sequence_random

Get a single SequenceRandom instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sequence_randoms property

sequence_randoms

List of all SequenceRandom instances.

genesis.version4.MainInput.setup property

setup

Get the required setup namelist.

genesis.version4.MainInput.sponrad property

sponrad

Get a single Sponrad instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.sponrads property

sponrads

List of all Sponrad instances.

genesis.version4.MainInput.time property

time

Get a single Time instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.times property

times

List of all Time instances.

genesis.version4.MainInput.track property

track

Get a single Track instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.tracks property

tracks

List of all Track instances.

genesis.version4.MainInput.wake property

wake

Get a single Wake instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.wakes property

wakes

List of all Wake instances.

genesis.version4.MainInput.write property

write

Get a single Write instance. Errors if zero or 2+ exist.

genesis.version4.MainInput.writes property

writes

List of all Write instances.

Functions

genesis.version4.MainInput.from_contents classmethod

from_contents(contents, filename=None)

Load main input from its file contents.

Parameters:

Name	Type	Description	Default
contents	str	The contents of the main input file.	required
filename	AnyPath or None	The filename, if known.	None

Returns:

Type	Description
MainInput

Source code in genesis/version4/input/core.py

@classmethod
def from_contents(
    cls, contents: str, filename: Optional[AnyPath] = None
) -> MainInput:
    """
    Load main input from its file contents.

    Parameters
    ----------
    contents : str
        The contents of the main input file.
    filename : AnyPath or None, optional
        The filename, if known.

    Returns
    -------
    MainInput
    """
    parser = parsers.new_main_input_parser()
    filename = filename or "unknown"
    try:
        tree = parser.parse(contents)
    except Exception:
        if "\n" not in contents:
            raise ValueError(
                f"Unable to parse the provided input in Genesis4 main input "
                f"format. It looks like this might have been a filename: "
                f"{contents!r}"
            )
        raise
    return _MainInputTransformer(filename).transform(tree)

genesis.version4.MainInput.from_dicts classmethod

from_dicts(contents, filename=None)

Load main input from a list of serialized dictionaries.

Parameters:

Name	Type	Description	Default
contents	sequence of dict	The serialized contents of the main input file.	required

Returns:

Type	Description
MainInput

Source code in genesis/version4/input/core.py

@classmethod
def from_dicts(
    cls, contents: Sequence[Dict], filename: Optional[pathlib.Path] = None
) -> MainInput:
    """
    Load main input from a list of serialized dictionaries.

    Parameters
    ----------
    contents : sequence of dict
        The serialized contents of the main input file.

    Returns
    -------
    MainInput
    """

    if isinstance(contents, dict):
        contents = [contents]

    adapter = pydantic.TypeAdapter(AnyNameList)

    def make_class(idx: int, dct: dict) -> AnyNameList:
        type_ = dct.get("type", None)
        if type_ is None:
            raise ValueError(f"'type' missing from dictionary #{idx}")

        try:
            return adapter.validate_python(dct)
        except pydantic.ValidationError as ex:
            raise ValueError(
                f"Dictionary #{idx} with type {type_!r} did not pass pydantic validation. "
                f"Are all parameters for the given class valid?"
            ) from ex

    return cls(
        namelists=[make_class(idx, dct) for idx, dct in enumerate(contents)],
        filename=filename,
    )

genesis.version4.MainInput.from_file classmethod

from_file(filename)

Load a main input file from disk.

Parameters:

Name	Type	Description	Default
filename	AnyPath	The filename to load.	required

Returns:

Type	Description
MainInput

Source code in genesis/version4/input/core.py

@classmethod
def from_file(cls, filename: AnyPath) -> MainInput:
    """
    Load a main input file from disk.

    Parameters
    ----------
    filename : AnyPath
        The filename to load.

    Returns
    -------
    MainInput
    """
    with open(filename) as fp:
        contents = fp.read()
    return cls.from_contents(contents, filename=filename)

genesis.version4.MainInput.from_tao classmethod

from_tao(tao, ele_start='beginning', branch=0, universe=1)

Creates Genesis4 MainInput from a Tao instance, using specified parameters to extract relevant beamline, beam, and field configurations.

Parameters:

Name	Type	Description	Default
tao	Tao	A running Tao instance, providing access to element attributes, Twiss parameters, and orbit data.	required
ele_start	str	Element to start. Defaults to "beginning".	'beginning'
branch	int	The branch index within the specified Tao universe. Defaults to 0.	0
universe	int	The universe index within the Tao object. Defaults to 1.	1

Returns:

Type	Description
MainInput

Notes

• The generated beamline name is based on the Tao universe and branch configuration, with gamma0 calculated from the total energy.

Examples:

>>> tao = pytao.Tao(...)
>>> input = MainInput.from_tao(tao, ele_start='beginning', branch=0, universe=1)

Source code in genesis/version4/input/core.py

@classmethod
def from_tao(
    cls, tao, ele_start: str = "beginning", branch: int = 0, universe: int = 1
):
    """
    Creates Genesis4 MainInput from a Tao instance, using specified parameters to
    extract relevant beamline, beam, and field configurations.

    Parameters
    ----------
    tao : pytao.Tao
        A running Tao instance, providing access to element attributes, Twiss parameters,
        and orbit data.
    ele_start : str, optional
        Element to start. Defaults to "beginning".
    branch : int, optional
        The branch index within the specified Tao universe. Defaults to 0.
    universe : int, optional
        The universe index within the Tao object. Defaults to 1.

    Returns
    -------
    MainInput

    Notes
    -----
    - The generated `beamline` name is based on the Tao universe and branch configuration,
      with `gamma0` calculated from the total energy.

    Examples
    --------
    >>> tao = pytao.Tao(...)
    >>> input = MainInput.from_tao(tao, ele_start='beginning', branch=0, universe=1)

    """
    namelists = genesis4_namelists_from_tao(
        tao, ele_start=ele_start, branch=branch, universe=universe
    )
    return cls(namelists=namelists)

genesis.version4.MainInput.insert_initial_field

insert_initial_field(field, harmonic=1, time=True)

Insert a FieldFile instance as as an initial field with importfield.

Source code in genesis/version4/input/core.py

def insert_initial_field(
    self,
    field: FieldFile,
    harmonic: int = 1,
    time: bool = True,
) -> int:
    """Insert a FieldFile instance as as an initial field with importfield."""
    to_insert = ImportField(
        file="initial_field.h5",
        harmonic=harmonic,
        time=time,
    )

    logger.debug("Inserting initial field file: %s", field)
    try:
        previous = self.import_field
    except NamelistAccessError:
        if self.fields:
            # Before Field, if it exists
            insert_pos = self.namelists.index(self.fields[0])
        elif self.times:
            # Otherwise, it needs to come after Time
            insert_pos = self.namelists.index(self.times[-1]) + 1
        else:
            logger.warning(
                "Unable to determine where to insert the importfield; "
                "placing it after 'setup'"
            )
            insert_pos = self.namelists.index(self.setup) + 1
    else:
        insert_pos = self.namelists.index(previous)
        self.remove(previous)

    self.namelists.insert(insert_pos, to_insert)
    return insert_pos

genesis.version4.MainInput.insert_initial_particles

insert_initial_particles(particles, update_slen)

Insert a ParticleGroup instance as as an initial particle distribution.

Source code in genesis/version4/input/core.py

def insert_initial_particles(
    self,
    particles: Union[ParticleGroup, Genesis4ParticleData],
    update_slen: bool,
) -> int:
    """Insert a ParticleGroup instance as as an initial particle distribution."""

    if isinstance(particles, ParticleGroup):
        to_insert = ImportDistribution(
            file="initial_particles.h5",
            charge=particles.charge,
        )
        to_remove = self.import_beams + self.beams
    else:
        to_insert = ImportBeam(file="initial_particles.h5")
        to_remove = self.import_distributions + self.beams

    for remove in to_remove:
        logger.warning(f"Removing existing {type(remove).__name__}")
        self.remove(remove)

    try:
        if isinstance(to_insert, ImportDistribution):
            previous = self.import_distribution
        else:
            previous = self.import_beam
    except NamelistAccessError:
        try:
            # Insert it after the time namelist:
            insert_pos = self.namelists.index(self.time) + 1
        except NamelistAccessError:
            # Last attempt: put it after setup
            insert_pos = self.namelists.index(self.setup) + 1
    else:
        insert_pos = self.namelists.index(previous)
        self.remove(previous)

    if update_slen and isinstance(particles, ParticleGroup):
        particles_slen = get_particles_slen(particles)
        for time_ in self.times:
            was = time_.slen
            if was < particles_slen:
                time_.slen = particles_slen
                logger.warning(
                    "Updating time namelist slen: %f (was %f) to span all particles",
                    time_.slen,
                    was,
                )

    self.namelists.insert(insert_pos, to_insert)
    return insert_pos

genesis.version4.MainInput.remove

remove(item_or_class)

Remove a item from the namelist by instance or class.

Parameters:

Name	Type	Description	Default
item_or_class	NameList class, instance, or list		required

Examples:

Remove a single instance of "Track" namelists.

>>> G.input.main.remove(G.input.main.track)

Remove a single instance of "Track" namelists.

>>> G.input.main.remove(G.input.main.track)

Remove all instances of "Track" namelists using the class:

>>> G.input.main.remove(Track)

Source code in genesis/version4/input/core.py

def remove(
    self, item_or_class: Union[AnyNameList, Type[NameList], Sequence[AnyNameList]]
) -> List[AnyNameList]:
    """
    Remove a item from the namelist by instance or class.

    Parameters
    ----------
    item_or_class : NameList class, instance, or list

    Examples
    --------

    Remove a single instance of "Track" namelists.

    >>> G.input.main.remove(G.input.main.track)

    Remove a single instance of "Track" namelists.

    >>> G.input.main.remove(G.input.main.track)

    Remove all instances of "Track" namelists using the class:

    >>> G.input.main.remove(Track)
    """
    to_remove: List[AnyNameList]
    if isinstance(item_or_class, NameList):
        to_remove = [item_or_class]
    elif isclass(item_or_class):
        to_remove = [
            obj for obj in list(self.namelists) if isinstance(obj, item_or_class)
        ]
    else:
        to_remove = list(item_or_class)

    for obj in to_remove:
        self.namelists.remove(obj)
    return to_remove

genesis.version4.MainInput.to_dicts

to_dicts(exclude_defaults=True, by_alias=True, **kwargs)

Serialize this main input to a list of dictionaries.

Source code in genesis/version4/input/core.py

def to_dicts(
    self,
    exclude_defaults: bool = True,
    by_alias: bool = True,
    **kwargs: Any,
) -> List[Dict]:
    """Serialize this main input to a list of dictionaries."""
    return [
        {
            "type": namelist.model_fields["type"].default,
            **namelist.model_dump(
                exclude_defaults=exclude_defaults, by_alias=by_alias, **kwargs
            ),
        }
        for namelist in self.namelists
    ]

genesis.version4.MainInput.to_file

to_file(filename)

Write the main input file, in Genesis format, to filename.

Parameters:

Name	Type	Description	Default
filename	str or Path		required

Source code in genesis/version4/input/core.py

def to_file(
    self,
    filename: AnyPath,
) -> None:
    """
    Write the main input file, in Genesis format, to ``filename``.

    Parameters
    ----------
    filename : str or pathlib.Path
    """
    main_config = self.to_genesis()
    with open(filename, "wt") as fp:
        print(main_config, file=fp)

    logger.debug(
        "Wrote main config to %s:\n%s",
        main_config,
        filename,
    )

genesis.version4.MainInput.write_files

write_files(workdir, main_filename='genesis4.in', source_path=Path(), rename=True)

Write the main input file, arrays and other necessary files to run Genesis to workdir.

This may modify setup or other namelists as required to generate valid Genesis4 input.

Parameters:

Name	Type	Description	Default
workdir	Path or str	The work directory where Genesis is to be run.	required
main_filename	str	Filename to use for the main input file.	= "genesis4.in"
source_path	Path or str	The source directory, where any referenced HDF5 files will be found. Defaults to the current directory.	Path()
rename	bool	Adjust temporary filenames of HDF5 files, replacing random characters with sensible namelist-prefixed names.	True

Returns:

Type	Description
List[Path]	The additional filenames that were written.

Source code in genesis/version4/input/core.py

def write_files(
    self,
    workdir: AnyPath,
    main_filename: str = "genesis4.in",
    source_path: AnyPath = pathlib.Path(),
    rename: bool = True,
) -> List[pathlib.Path]:
    """
    Write the main input file, arrays and other necessary files to run
    Genesis to ``workdir``.

    This may modify ``setup`` or other namelists as required to generate
    valid Genesis4 input.

    Parameters
    ----------
    workdir : pathlib.Path or str
        The work directory where Genesis is to be run.
    main_filename : str, default = "genesis4.in"
        Filename to use for the main input file.
    source_path : pathlib.Path or str, optional
        The source directory, where any referenced HDF5 files will be
        found.  Defaults to the current directory.
    rename : bool, optional
        Adjust temporary filenames of HDF5 files, replacing random
        characters with sensible namelist-prefixed names.

    Returns
    -------
    List[pathlib.Path]
        The additional filenames that were written.
    """
    self._check_for_mistakes()

    workdir = pathlib.Path(workdir).resolve()
    source_path = pathlib.Path(source_path).resolve()
    if not workdir.exists():
        raise ValueError(f"The configured work directory {workdir} does not exist")
    if not workdir.is_dir():
        raise ValueError(
            f"The configured work directory {workdir} is not a directory"
        )

    # We expect that external files are provided by the user in the
    # same directory as the input files.  Verify they exist first.
    for namelist, filename in self._get_files_to_symlink(workdir):
        source_file = source_path / filename
        if not source_file.exists():
            raise FileNotFoundError(f"{source_file} (referenced in {namelist})")

    paths = []
    # Write out arrays to temporary HDF5 files so the user doesn't have to:
    for cls in (ProfileArray,):
        for idx, namelist in enumerate(self.by_namelist.get(cls, [])):
            if rename or not namelist.filename:
                namelist.filename = f"{cls.__name__}_{idx}.h5"
            paths.append(namelist.write(workdir))

    # Symlink user-referenced pre-existing HDF5 files:
    for _, filename in self._get_files_to_symlink(workdir):
        source_file = source_path / filename
        symlink = workdir / filename
        _symlink_or_copy(symlink=symlink, file=source_file)

        paths.append(symlink)

    # Write the main input file last, as temporary filenames may have
    # changed above.
    self.to_file(workdir / main_filename)
    paths.append(workdir / main_filename)
    return paths

Main Input Namelists

Base class

genesis.version4.input.core.NameList

Bases: BaseModel, ABC

Base class for name lists used in Genesis 4 main input files.

Functions

genesis.version4.input.core.NameList.to_genesis

to_genesis()

Create a Genesis 4-compatible namelist from this instance.

Source code in genesis/version4/types.py

def to_genesis(self) -> str:
    """Create a Genesis 4-compatible namelist from this instance."""
    from .input.util import python_to_namelist_value

    parameters = (
        f"  {name} = {python_to_namelist_value(value)}"
        for name, value in self._to_genesis_params.items()
    )
    return "\n".join(
        (
            f"&{self.type}",
            *parameters,
            "&end",
        )
    )

Namelists

genesis.version4.Setup

Bases: NameList

The namelist setup is a mandatory namelist and should be the first in the input deck. It contains the basic parameters to control the simulations. It can only be called once. If the user want to change some parameter the namelist alter_setup should be used.

Setup corresponds to Genesis 4 namelist setup.

Attributes:

Name	Type	Description
rootname	str, default=""	The basic string, with which all output files will start, unless the output filename is directly overwritten (see write namelist)
outputdir	str, default=""	Output directory name.
lattice	str, default=""	The name of the file which contains the undulator lattice description. This can also include some relative paths if the lattice file is not in the same directory as the input file.
beamline	str, default=""	The name of the beamline, which has to be defined within the lattice file. For more information on the lattice file, see the next chapter.
gamma0	float, default=11350.3	The reference energy in unites of the electron rest mass. This is the reference energy which is used in the code at various place, mostly in the calculation of the matching condition, the reference focusing strength of quadrupoles and undulator as well as the default value if an electron distribution is generated.
lambda0	float, default=1e-10	The reference wavelength in meter, which is used as the wavelength in steady- state simulation or for defining the sample distance in time-dependent runs. It also acts as the default value when field distributions are generated.
delz	float, default=0.015	Preferred integration stepsize in meter. Note that this is not a strict value because Genesis tries to optimized the stepsize according to the elements it can resolve. E.g. if an undulator is 1.99 m long but the preferred stepsize is 2 cm than it uses a stepsize which is the closest to preserve the number of integration step. In this case the preferred stepsize gives 99.5 steps which is than rounded to 100 and thus resulting in an actual stepsize of 1.99 cm. Note that outside of the undulator, which are free drifts for the radiation field, Genesis progresses the electron beam and radiation field in larger steps, namely one step per resolved element (drift, quadrupole, phase shifter).
seed	int, default=123456789	Seed to initialize the random number generator, which is used for shot noise calculation and undulator lattice errors, though it is recommended that the random number generator seed is redefined explicitly for undulator errors in its corresponding namelist.
npart	int, default=8192	Number of macro particles per slice. Note that the number must be a multiple of the used bins nbins otherwise Genesis will exit with an error. If one-for-one simulations are used, this parameter has no meaning.
nbins	int, default=4	Number of macro particles, which are grouped into beamlets for gener ating the correct shot noise. For one-for-one simulations this parameter has no meaning
one4one	bool, default=False	Flag to enable or disable resolving each electron in the simulation. This is mandatory for certain features, such as sorting or slicing of particle distributions. If set to true other parameters such as npart and nbins are obsolete and do not need to be defined. It is recommended to estimate the number of electrons, which are generated in the simulations, because this can easily required memory beyond what is available on the computer.
shotnoise	bool, default=True	Flag to enable the calculation of shotnoise per each slice during generation of the electron distribution. It is recommended to set the value to false for steady-state or scan simulations.
beam_global_stat	bool, default=False	Flag to enable extra output of beam parameters of the entire bunch, such as energy, energy spread etc. The data are placed in the HDF group ”Global” within the group ”Beam” of the output file
field_global_stat	bool, default=False	Flag for the field output, similar to beam_global_stat.
exclude_spatial_output	bool, default=False	Flag to suppress the datasets in the output file for the x- and y-position and size (both Beam and Field) and px- and py-position (Beam only). This might be useful to reduce the file size of the output file, if these datasets are not needed for the post-processing
exclude_fft_output	bool, default=False	Flag to suppress the datasets in the output file for the field divergence and pointing. Since it also disable the FFT calculation of the 2D wavefronts it speeds up the execution time slightly. If the code has been compiled without the support of the FFTW library this parametr has no effect.
exclude_intensity_output	bool, default=False	Flag to suppress the datasets for the near and farfield intensity and phase for the radiation field. If excluded the output file size becomes smaller but no post-processing calculation of the spectra is possible.
exclude_energy_output	bool, default=False	Flag to suppress the datasets in the output file for the mean energy and energy spread of the electron beam.
exclude_aux_output	bool, default=False	Flag to suppress the auxiliary datasets in the output file. In the moment it is the long-range longitudinal electric field as seen by the electrons.
exclude_current_output	bool, default=True	Flag to reduce the size of the current dataset for the electron beam. Under most circumstances the current profile is constant and only the initial current profile is written out. However, simulation with one-4-one set to true and sorting events the current profile might change. Example are ESASE/HGHG schemes. By setting the flag to false the current profile is written out at each output step similar to radiation power and bunching profile.
exclude_field_dump	bool, default=False	Exclude the field dump to .fld.h5.
write_meta_file	bool, default=False	Write a metadata file.
semaphore_file_name	str, default=""	Providing a file name for the semaphore file always switches on writing the "done" semaphore file, overriding 'write_semaphore_file' flag. This allows to switch on semaphore functionality just by specifying corresponding command line argument -- no modification of G4 input file needed.
write_semaphore_file	bool, default=False	Write a semaphore file when the simulation has completed.
write_semaphore_file_done	bool, default=False	Alias for write_semaphore_file. This takes precedence over write_semaphore_file if both are specified.
write_semaphore_file_started	bool, default=False	Write a semaphore file at startup, after the setup block is parsed.

genesis.version4.AlterField

Bases: NameList

Field manipulator (TODO).

Note that the namelist field_manipulator is deprecated and will be removed in the future. Use alter_field instead.

AlterField corresponds to Genesis 4 namelist alter_field.

Attributes:

Name	Type	Description
harm	int, default=1	harmonic
scale_power	float, default=1.0	power scaling factor
spp_l	float, default=0.0	TODO
spp_nsect	int, default=0	TODO
spp_phi0	float, default=0.0	TODO

genesis.version4.AlterSetup

Bases: NameList

A namelist to change some parameters within the simulation, which have been defined alread by the setup-namelist. The change values are stored in the setup module so that for another invocation of alter_setup some defaults values are use which have been defined in the preceding call of alter_setup

AlterSetup corresponds to Genesis 4 namelist alter_setup.

Attributes:

Name	Type	Description
rootname	str, default=""	The basic string, with which all output files will start, unless the output filename is directly overwritten (see write-namelist)
beamline	str, default=""	The name of the beamline, which has to be defined within the lattice file. This way another beamline can be selected in the case the simulation has multiple stages
delz	float, default=0.0	Preferred integration stepsize in meter. Note that this is not a strict value because Genesis tries to optimized the stepsize according to the elements it can resolve. E.g. if an undulator is 1.99 m long but the preferred stepsize is 2 cm than it uses a stepsize which is the closes to preserve the number of integration step. In this case the preferred stepsize gives 99.5 steps which is than rounded to 100 and thus resulting in an actual stepsize of 1.99 cm. Note that outside of the undulator Genesis, which are free drifts for the radiation field, it progress the electron beam and radiation field in larger steps, namely one step per resolved element (drift, quadrupole, phase shifter).
harmonic	int, default=1	If the value is not 1 than a harmonic conversion is done. This has several consequences. The reference wavelength in setup is divided by the harmonic number, the sample rate in time is multiplied by the harmonic number, the ponderomotive phases of all macro particles are scaled with the harmonic number, all radiation fields, which are not identical to the harmonic numbers are deleted, while an existing harmonic field is changed to be at the fundamental wavelength
subharmonic	int, default=1	If the value is not 1 than a down conversion is done. It is similar to the action of harmonics but in the opposite directions. For the radiation field all field definitions are deleted except for the fundamental, which is converted to a harmonic. In this case the fundamental field needs to be defined before another tracking is called.
resample	bool, default=False	If this is set to true and only if one-for-one simulations are used the harmonic and subharmonic conversion can re-sample to the new wavelength. In the case of up-conversion the slices are split and the total number of slices increases. Same with the radiation field. An previously existing harmonic field, which is now becoming the fundamental, is interpolated between the existing sample points (still needs to be implemented). If a new field is generated it has automatically the new number of slices. If also prevents that the sample rate is changed by remaining unchanged.
disable	bool, default=False	Disable non-matching radiation harmonic.

genesis.version4.Beam

Bases: NameList

This namelist initiates the generation of the particle distribution to be kept in memory. Any time-dependence has to be defined before calling this namelist.

Beam corresponds to Genesis 4 namelist beam.

Attributes:

Name	Type	Description
gamma	float, default=0.0	Mean energy in units of the electron rest mass. If default value is given by the reference energy from the setup-namelist.
delgam	float, default=0.0	RMS energy spread in units of the electron rest mass.
current	float, default=1000.0	Current in Amperes.
ex	float, default=3e-07	Normalized emittance in \(x\) in units of meters
ey	float, default=3e-07	Normalized emittance in \(y\) in units of meters
betax	float, default=15.0	Initial beta-function in \(x\) in meters. If the matched command has been invoked before the default values are set to the results.
betay	float, default=15.0	Initial beta-function in \(y\) in meters. If the matched command has been invoked before the default values are set to the results.
alphax	float, default=0.0	Initial alpha-function in \(x\). If the matched command has been invoked before the default values are set to the results.
alphay	float, default=0.0	Initial alpha-function in \(y\). If the matched command has been invoked before the default values are set to the results.
xcenter	float, default=0.0	Initial centroid position in \(x\) in meter.
ycenter	float, default=0.0	Initial centroid position in \(y\) in meter.
pxcenter	float, default=0.0	Initial centroid momentum in \(x\) in units of \(\gamma \beta_x\).
pycenter	float, default=0.0	Initial centroid momentum in \(y\) in units \(\gamma \beta_y\).
bunch	float, default=0.0	Initial bunching value
bunchphase	float, default=0.0	Initial phase of the bunching
emod	float, default=0.0	Initial energy modulation in units of the electron rest mass. This modulation is on the scale of the reference wavelength
emodphase	float, default=0.0	Initial phase of the energy modulation

genesis.version4.Efield

Bases: NameList

This namelist controls the long and short range space charge fields. The long range corresponds to any length scale longer than the slice length of the simulation, while the short range is on the resonant wavelength scale. Numerically they are treated differently. The calculation for the short range is done on a radial-azimuthal grid, centered to the centroid position of the electron slice, while the long range is the sum of the space charge field in the rest frame where each slice is treated as a uniform disk.

Efield corresponds to Genesis 4 namelist efield.

Attributes:

Name	Type	Description
longrange	bool, default=False	Flag to enable the calculation of the long range space charge field.
rmax	float, default=0.0	Size of radial grid in meters. If the beam size gets larger than the grid the size is automatically adjusted to the maximum radius of the electrons with an additional 50% extension. When the mesh size is adjusted a message will be printed on screen.
nz	int, default=0	Number of longitudinal Fourier component of the short range space charge field. Note that this should be not in conflict with the beamlet size.
nphi	int, default=0	Number of azimuthal modes in the calculation of the short range space charge field.
ngrid	int, default=100	Number of grid points of the radial grid for the short range space charge field.

genesis.version4.Field

Bases: NameList

This namelist initiate the generation of the field distribution. It differs in one point from the generation of the beam. It can be called multiple times. If the variable accumulate is set to true, it does not delete the previous distribution but adds up the wavefronts. That way higher mode content in either spatial and time direction can be created.

Field corresponds to Genesis 4 namelist field.

Attributes:

Name	Type	Description
lambda_	float, default=0.0	Central frequency of the radiation mode. The default value is the reference wavelength from the setup-namelist.
power	float, default=0.0	Radiation power in Watts
phase	float, default=0.0	radiation phase in rads. Note that a linear profile results in a shift in the radiation wavelength, which is also the method if for the variable lambda a different value than the reference wavelength is used. In case of conflicts the profile for the phase definition has priority.
waist_pos	float, default=0.0	Position where the focal point is located relative to the undulator entrance. Negative values place it before, resulting in a diverging radiation field.
waist_size	float, default=1e-07	Waist size according to the definition of \(w_0\) according to Siegman’s ’Laser’ handbook
xcenter	float, default=0.0	Center position in \(x\) in meter of the Gauss-Hermite mode
ycenter	float, default=0.0	Center position in \(y\) in meter of the Gauss-Hermite mode
xangle	float, default=0.0	Injection angle in \(x\) in rad of the Gauss-Hermite mode
yangle	float, default=0.0	Injection angle in \(y\) in rad of the Gauss-Hermite mode
dgrid	float, default=0.001	Grid extension from the center to one edge. The whole grid is twice as large with 0 as the center position
ngrid	int, default=151	Number of grid points in one dimension. This value should be odd to enforce a grid point directly on axis. Otherwise the convergence in the simulations could be worse.
harm	int, default=1	Harmonic number of the radiation field with respect to the reference wavelength.
nx	int, default=0	Mode number in \(x\) of the Gauss-Hermite mode
ny	int, default=0	Mode number in \(y\) of the Gauss-Hermite mode
accumulate	bool, default=False	If set the generated field is added to an existing field instead of overwriting it.

genesis.version4.ImportBeam

Bases: NameList

The modules controls the import of a Genesis 1.3 particle file to replace the internal generation of the particle distribution (note that the module beam should not be called). The routine defines also the parameter for a time- dependent run if the time-namelist hasn’t been defined yet.

ImportBeam corresponds to Genesis 4 namelist importbeam.

Attributes:

Name	Type	Description
file	str, default=""	File name of a hdf5 complient datafile to contain the slice-wise particle distribution. It has to follow the internal Genesis 1.3 syntax.
time	bool, default=True	If the time window hasn’t be defined it allows to run Genesis with the imported distribution in scan mode, when set to false. This would disable all slippage and long-range collective effects in the simulation

genesis.version4.ImportDistribution

Bases: NameList

This namelist controls the import of an external distribution which are generated from Elegant. The file has to be in HDF5 format. In the distribution is a shell script to convert an Elegant sdds-output file into the HDF5 format. The distribution has to provide all 6 dimensions while the charge is supplied in this namelist. When imported the longitudinal position is changed so that the last particles is at \(s=0\) micron.

Genesis will import the distribution and evaluate a part of the distribution in terms of emittance, twiss function etc. The part is defined by the parameters eval_start and eval_end. They are given in relative terms with respect to the total length of the distribution. E.g. values of 0.25 and 0.75 for these two parameters, respectively will use the central 50% of the bunch to determine the twiss function.

The beam can be match to new twiss parameters defined explicitly in the input deck or by the default values. Note that the matching region is defined by the evaluation range. So it is possible to match a certain slice in the distribution and the rest of the distribution will follow that distribution.

The flag settimewindow will update the length of the timewindow. But it is required that a time window is enabled in the input deck first. Also in this case import distribution needs to be called before the field definition.

One important parameter is slicewidth, with is the relative length of a slice in the distribution, for which the contained particles are used to recreate the internal distribution. It is a rolling window averaging of the particle distribution. Here a compromise has to be found between sufficient resolution to retrieve the time-dependent variation in current, emittance etc and having sufficient particles for a valid reconstruction. A crude rule of thumb is that in average there should be at least 1000 particle for the recreation. As an example: a distribution of 200000 particles would allow for 200 slices with about 1000 particles in it. These 200 slices correspond to a slicewidth of 0.005.

ImportDistribution corresponds to Genesis 4 namelist importdistribution.

Attributes:

Name	Type	Description
file	str, default=""	The file name of the distribution, including possible relative directories.
charge	float, default=0.0	Total charge of the distribution to calculate the current and individual charge per macro particle.
slicewidth	float, default=0.01	the fraction in length of the distribution which is used for reconstruction. E.g if the length is 10 micron and slic ewidth 0.02 then the reconstruction at the positions \(s= 4\,\mu m\) is using those particles in the distribution, which are located in the slice from \(3.9\, \mu m\) to \(4.1\,\mu m\).
center	bool, default=False	If set to true the particle distribution is recentered in transverse position, momenta and energy.
gamma0	float, default=0.0	If centering is enabled, new center in energy in units of electron rest mass.
x0	float, default=0.0	If centering is enabled, new center in \(x\) in meter.
y0	float, default=0.0	If centering is enabled, new center in \(y\) in meter.
px0	float, default=0.0	If centering is enabled, new mean momentum in \(x\) in \(\gamma \beta_x\).
py0	float, default=0.0	If centering is enabled, new mean momentum in y in \(\gamma \beta_y\).
match	bool, default=False	If set to true, the particle distribution is matched to new optical function values.
betax	float, default=15.0	If matching is enabled, new beta function in \(x\) in meters.
betay	float, default=15.0	If matching is enabled, new beta function in \(y\) in meters.
alphax	float, default=0.0	If matching is enabled, new alpha function in \(x\).
alphay	float, default=0.0	If matching is enabled, new alpha function in \(y\).
eval_start	float, default=0.0	evaluation start.
eval_end	float, default=1.0	evaluation end.
settimewindow	bool, default=False	set time window.
align	int, default=0	currently unused.
align_start	float, default=0.0	currently unused.
align_end	float, default=1.0	currently unused.

genesis.version4.ImportField

Bases: NameList

The modules controls the import of a Genesis 1.3 field file to replace the internal generation of the field distribution (note that the module field should only be called afterwards with the accumulate-option enabled). The routine defines also the parameter for a time-dependent run if the time-namelist hasn’t been defined yet.

ImportField corresponds to Genesis 4 namelist importfield.

Attributes:

Name	Type	Description
file	str, default=""	File name of a hdf5 compliant datafile to contain the slice-wise particle distribution. It has to follow the internal Genesis 1.3 syntax.
harmonic	int, default=1	defines the harmonic for the given Genesis run.
time	bool, default=True	If the time window hasn’t be defined it allows to run Genesis with the imported distribution in scan mode, when set to false. This would disable all slippage and long-range collective effects in the simulation

genesis.version4.ImportTransformation

Bases: NameList

Once an electron distribution is generated the namelist can be used to manipulate the distribution by shifting the particle by the vector dr or applying the transport matrix R. The applied transformation is r1 = R*r0+dr, where r0 is the initial particle vector and r1 the final one. The transformation assumes the standard 6D vector of (x,x',y,y',s,delta). the supplied vector and matrix must have the corresponding shape (6 or 6x6). The user can supply more than one vector or matrix, e.g. sampling at various positions s. Then the transformation used interpolated values. Note that in the case of transport matrices and interpolated matrix does not preserve the emittance. In this case a high sample rate should be supplied to reduce this effect to a minimum. Genesis will check the shape of the transport vector and matrices. If the rank is higher than needed (e.g. 2x6x6 for a transport matrix) then it assumes the first index refers to the sample along the s-axis. In this case the sample distance slen should be also specified. In the case that n=1 or slen=0 only a global transformation is applied.

ImportTransformation corresponds to Genesis 4 namelist importtransformation.

Attributes:

Name	Type	Description
file	str, default=""	File name of a hdf5 compliant datafile to contain the vector and matrix informations
vector	str, default=""	Name of the dataset which contains the vector information. The shape must be either (6) or (n,6)
matrix	str, default=""	Name of the dataset which contains the matrix information. The shape must be either (6,6) or (n,6,6)
slen	float, default=0.0	The length in meters between adjacent sample points (n>1), needed for the interpolation. If the value is zero only a global transformation is applied using the first entry.

genesis.version4.LatticeNamelist

Bases: NameList

This namelist is used to change the raw lattice from the lattice file, such as generating errors in the position of the elements. The namelist can be defined several times to add more than one error source to the lattice.

LatticeNamelist corresponds to Genesis 4 namelist lattice.

Attributes:

Name	Type	Description
zmatch	float, default=0.0	If the position within the undulator in meter is non-zero than Genesis tries to calculate the matched optics function for a periodic solution. In the case that it cannot find a solution than it will report it. Found solution will also be the default values for a succeeding beam generation, so that no explicit optical functions need to be defined any longer. If the lattice is highly non- periodic it is recommended to find the matching condition with an external program such as MAdX.
element	str, default=""	Name of the element type, which will be changed, e.g. Undulator if undulator modules are altered. Only the first 4 letters need to be defined. If there is no match, e.g. due to a type, nothing will be changed. It acts rather as a filter than a mandatory element. Elements of the type MARKER are not supported.
field	str, default=""	attribute name for a given element. The names are the same as in the definition of the lattice file. The field acts as a filter again. With non-matching events nothing will be changed.
value	float, default=0.0	The new value. If a reference to a sequence is used, values can be different depending on how many elements are changed. For a double the value would be the same for all elements affected.
instance	int, default=0	The instances of affected elements. If a positive value is given, than only that element is changed, where its occurence matches the number. E.g. for a value of 3 only the third element is selected. For a value of 0 all elements are changed. The ability to change more than one but less than all is currently not supported.
add	bool, default=True	If the value is true, the changes are added to the existing value. For a value of false, the old values are overwritten.
resolvePeriod	bool, default=False	currently unused.

genesis.version4.ProfileArray

Bases: NameList

ProfileArray is a lume-genesis convenience class for generating profile_file namelists.

Attributes:

Name	Type	Description
x_label	str	Name of the profile, which is used to refer to it in later calls of namelists
xdata	list of float or np.ndarray	The s-position for the look-up table.
ydata	list of float or np.ndarray	The function values of the look-up table.
isTime	bool, default=False	If true the s-position is a time variable and therefore multiplied with the speed of light c to get the position in meters.
reverse	bool, default=False	if true the order in the look-up table is reverse. This is sometimes needed because time and spatial coordinates differ sometimes by a minus sign.
filename	(str, optional)	By default, this is a randomly-generated filename that lume-genesis manages for you. If desirable, you may set a fixed filename relative to the main input file. Path delimiters (such as /) are not allowed.
x_label	(str, optional)	The X label (key) to use for the saved data.
y_label	(str, optional)	The Y label (key) to use for the saved data.

Functions

genesis.version4.ProfileArray.get_hdf_data

get_hdf_data()

Get all HDF5 data to be written for Genesis 4.

Source code in genesis/version4/input/core.py

def get_hdf_data(self) -> Dict[str, np.ndarray]:
    """Get all HDF5 data to be written for Genesis 4."""
    return {
        self.x_label: self.xdata,
        self.y_label: self.ydata,
    }

genesis.version4.ProfileArray.to_profile_file

to_profile_file()

Convert this ProfileArray into a 'profile_file' namelist for Genesis 4.

Source code in genesis/version4/input/core.py

def to_profile_file(self) -> ProfileFile:
    """Convert this ProfileArray into a 'profile_file' namelist for Genesis 4."""
    return ProfileFile(
        label=self.label,
        xdata=f"{self.filename}/{self.x_label}",
        ydata=f"{self.filename}/{self.y_label}",
        isTime=self.isTime,
        reverse=self.reverse,
        autoassign=self.autoassign,
    )

genesis.version4.ProfileConst

Bases: NameList

ProfileConst corresponds to Genesis 4 namelist profile_const.

Attributes:

Name	Type	Description
label	str	Name of the profile, which is used to refer to it in later calls of namelists
c0	float, default=0.0	constant value to be used.

genesis.version4.ProfileFile

Bases: NameList

ProfileFile corresponds to Genesis 4 namelist profile_file.

Attributes:

Name	Type	Description
label	str	Name of the profile, which is used to refer to it in later calls of namelists
xdata	str, default=""	Points to a dataset in an HDF5 file to define the s-position for the look-up table. The format is filename/group1/.../groupn/datasetname, where the naming of groups is not required if the dataset is at root level of the HDF file
ydata	str, default=""	Same as y data but for the function values of the look-up table.
isTime	bool, default=False	If true the s-position is a time variable and therefore multiplied with the speed of light c to get the position in meters.
reverse	bool, default=False	if true the order in the look-up table is reverse. This is sometimes needed because time and spatial coordinates differ sometimes by a minus sign.
autoassign	bool, default=False	use the HDF5 file from xdata (TODO more details).

genesis.version4.ProfileFileMulti

Bases: NameList

Generates profile objects <label_prefix>.gamma, <label_prefix>.delgam, <label_prefix>.current, etc., each one corresponding to one &profile_file.

ProfileFileMulti corresponds to Genesis 4 namelist profile_file_multi.

Attributes:

Name	Type	Description
file	str, default=""	HDF5 filename.
label_prefix	str, default=""	prefix for each object.
xdata	str, default=""	Points to a dataset in an HDF5 file to define the s-position for the look-up table. The format is filename/group1/.../groupn/datasetname, where the naming of groups is not required if the dataset is at root level of the HDF file
ydata	str, default=""	Same as y data but for the function values of the look-up table.
isTime	bool, default=False	If true the s-position is a time variable and therefore multiplied with the speed of light c to get the position in meters.
reverse	bool, default=False	if true the order in the look-up table is reverse. This is sometimes needed because time and spatial coordinates differ sometimes by a minus sign.

genesis.version4.ProfileGauss

Bases: NameList

ProfileGauss corresponds to Genesis 4 namelist profile_gauss.

Attributes:

Name	Type	Description
label	str	Name of the profile, which is used to refer to it in later calls of namelists
c0	float, default=0.0	Maximum function value of the Gaussian distribution
s0	float, default=0.0	Center point of the Gaussian distribution
sig	float, default=0.0	Standard deviation of the Gaussian distribution

genesis.version4.ProfilePolynom

Bases: NameList

ProfilePolynom corresponds to Genesis 4 namelist profile_polynom.

Attributes:

Name	Type	Description
label	str	Name of the profile, which is used to refer to it in later calls of namelists
c0	float, default=0.0	Constant term
c1	float, default=0.0	Term proportional to s
c2	float, default=0.0	Term proportional to s^2
c3	float, default=0.0	Term proportional to s^3
c4	float, default=0.0	Term proportional to s^4

genesis.version4.ProfileStep

Bases: NameList

ProfileStep corresponds to Genesis 4 namelist profile_step.

Attributes:

Name	Type	Description
label	str	Name of the profile, which is used to refer to it in later calls of namelists
c0	float, default=0.0	Constant term
s_start	float, default=0.0	Starting point of the step function
s_end	float, default=0.0	Ending point of the step function

genesis.version4.SequenceConst

Bases: NameList

SequenceConst corresponds to Genesis 4 namelist sequence_const.

Attributes:

Name	Type	Description
label	str	Name of the sequence, which is used to refer to it in the lattice
c0	float, default=0.0	constant value to be used.

genesis.version4.SequenceFilelist

Bases: NameList

A sequence list with data in a file.

SequenceFilelist corresponds to Genesis 4 namelist sequence_filelist.

Attributes:

Name	Type	Description
label	str	label for the sequence.
file	str, default=""	filename to load the sequence from with one line per value.

genesis.version4.SequenceList

Bases: NameList

A sequence of values given as a string.

SequenceList corresponds to Genesis 4 namelist sequence_list.

Attributes:

Name	Type	Description
label	str	label for the sequence.
val	float, default=[]	list of values.
default	float, default=0.0	default value to use for out-of-bound indices.

genesis.version4.SequencePolynom

Bases: NameList

SequencePolynom corresponds to Genesis 4 namelist sequence_polynom.

Attributes:

Name	Type	Description
label	str	Name of the sequence, which is used to refer to it in the lattice
c0	float, default=0.0	Constant term
c1	float, default=0.0	Term proportional to s
c2	float, default=0.0	Term proportional to s^2
c3	float, default=0.0	Term proportional to s^3
c4	float, default=0.0	Term proportional to s^4

genesis.version4.SequencePower

Bases: NameList

SequencePower corresponds to Genesis 4 namelist sequence_power.

Attributes:

Name	Type	Description
label	str	Name of the sequence, which is used to refer to it in the lattice
c0	float, default=0.0	Constant term
dc	float, default=0.0	Term scaling the growing power series before added to the constant term
alpha	float, default=0.0	power of the series
n0	int, default=1	starting index of power growth. Otherwise the sequence uses only the constant term

genesis.version4.SequenceRandom

Bases: NameList

SequenceRandom corresponds to Genesis 4 namelist sequence_random.

Attributes:

Name	Type	Description
label	str	Name of the sequence, which is used to refer to it in the lattice
c0	float, default=0.0	Mean value
dc	float, default=0.0	Amplitude of the error, either the standard division for normal distribution or the min and max value for uniform distribution.
seed	int, default=100	seed for the random number generator
normal	bool, default=True	Flag for Gaussian distribution. If set to false a uniform distribution is used.

genesis.version4.Sponrad

Bases: NameList

This enables the effect of spontaneous radiation outside of the frequency band of the FEL simulation.

Sponrad corresponds to Genesis 4 namelist sponrad.

Attributes:

Name	Type	Description
seed	int, default=1234	Seed for random number generator to model the quantum fluctuation of hard photons.
doLoss	bool, default=False	If set to true, electrons will loose energy due to the emission of spontaneous radiation within the undulator
doSpread	bool, default=False	If set to true, the energy spread will increase due to the fluctuation in the emission of hard photons of the spontaneous radiation.

genesis.version4.Time

Bases: NameList

This namelist defines the time window/range for simulation with more than just one slice. For reference the complementary axis of the undulator axis, which is normally the position in the time frame, is expressed in a position s. Normally everything is aligned to the origins = 0, in particular when external distributions are imported. Note that for parallel execution the number of slices per core must be the same for an efficient writing of the output files. Therefore Genesis extends the time-window to symmetrize the number of slices per core by extending it towards larger values of s. As an example, with XLAMDS=1e-6 and a length SLEN=20e-6 a call of Genesis with 24 cores would generate a time-window of 24 microns because each core would have one slice, while 15 cores would expand it to 30 microns with 2 slices per core each.

This module defines also scans in either field or beam parameters if the corresponding flag is set. Technically it generates the beam and field as for time-dependence but disables slippage during simulations. That way the radiation field is kept in the same slice, acting as steady-state simulations.

Time corresponds to Genesis 4 namelist time.

Attributes:

Name	Type	Description
s0	float, default=0.0	Starting point of the time-window in meters.
slen	float, default=0.0	Length of the time window in meters. Note that for parallel jobs this might be adjusted towards larger values.
sample	int, default=1	Sample rate in units of the reference wavelength from thesetup namelist, so that the number of slices is given by SLEN / LAMBDA0 /SAMPLE after SLEN has been adjusted to fit the MPI size.
time	bool, default=True	Flag to indicate time-dependent run. Note that time-dependent simulations are enabled already by using this namelist. This flag has the functionality to differentiate between time-dependent run and scans, which disable the slippage in the tracking. To restrict the simulation to steady-state the time namelist has to be omitted from the input deck.

genesis.version4.Track

Bases: NameList

This namelist initiate the actually tracking through the undulator and then writing out the results. Normally all parameter should be defined before or defined in the lattice but the namelist allows some ’last minute’ change of the behavior of the code

Track corresponds to Genesis 4 namelist track.

Attributes:

Name	Type	Description
zstop	float, default=1000000000.0	If zstop is shorter than the lattice length the tracking stops at the specified position.
output_step	int, default=1	Defines the number of integration steps before the particle and field distribution is analyzed for output.
field_dump_step	int, default=0	Defines the number of integration steps before a field dump is written. Be careful because for time-dependent simulation it can generate many large output files.
beam_dump_step	int, default=0	Defines the number of integration steps before a particle dump is written. Be careful because for time-dependent simulation it can generate many large output files.
sort_step	int, default=0	Defines the number of steps of integration before the particle distribution is sorted. Works only for one-4-one simulations.
s0	float, default=0.0	Option to override the default time window start from the TIME module.
slen	float, default=0.0	Option to override the default time window length from the TIME module.
field_dump_at_undexit	bool, default=False	Field dumps at the exit of the undulator (one dump for each undulator in the expanded lattice).
bunchharm	int, default=1	Bunching harmonic output setting. Must be >= 1.

genesis.version4.Wake

Bases: NameList

Genesis supports the calculation of three types of wakefields by specifying the typical input parameters (e.g. gap length for the geometric wakefield). It first solves the single particle wake and then convolutes with the current distribution. Therefore it follows the change in the wakepotential if a chirped beams undergoes a compression in a chicane. In addition an external loss factor can be supplied, which can also refer to a profile. In this case it is treated as the full wake and subtracted from the particle energy directly.

Note that this functionality hasn't been fully tested yet or optimized for rapid calculation

Wake corresponds to Genesis 4 namelist wake.

Attributes:

Name	Type	Description
loss	float, default=0.0	Loss in \(eV/m\). This is a global loss function (in particular if a profile is defined). Its function values V(s) remains unchanged even if the current profile changes
radius	float, default=0.0025	Radius of the aperture if it is a round chanber or half the distance in the case of two parallel plates.
roundpipe	bool, default=True	Flag to indicate the shape of the transverse cross-section of the aperture. If set to true, a round aperture is assumed, otherwise the model has two parallel plates.
conductivity	float, default=0.0	Conductivity of the vacuum material for the resistive wall wakefield function
relaxation	float, default=0.0	Relaxation distance (aka the mean free path of the electron in the vacuum material) for the resistive wall wakefields
material	str, default=""	String literal to define conductivity and relaxation distance for either copper or aluminum by using the two character label ’CU’ or ’AL’ repectively. This overwrites also any explicit definition of the conductivity and relaxation value.
gap	float, default=0.0	Length in mm of a longitudinal gap in the aperture, exciting geometric wakes.
lgap	float, default=1.0	Effective length over which a single gap is applied. E.g. if there is a periodicity of 4.5 m at which there is always the same gap in the aperture for the geometrice wakes, then this value should be put to 4.5 m.
hrough	float, default=0.0	Amplitude in meters of a sinusoidal corrugation, modeling the effect of surface roughness wakes.
lrough	float, default=1.0	period lengthin meters of the sinusoidal corrugation of the surface roughness model.
transient	bool, default=False	If set to true, Genesis includes the catch-up length of the origin of the wakefield to the particle effects. E.g. particles do not see immediatly the wake from those closer ahead of them than those further away. The catch-up distance is the distance in the undulator added to the starting position ztrans. If set to false the steady-state model is used, effectively setting ztrans to infinity. Enabling transient calculation will update the wakefield at each integration step, which can slow down the calculations.
ztrans	float, default=0.0	Reference location of the first source of the wake fields. A positive value means that the condition for wakes (e.g. a small aperture in the vacuum chamber) has already started and there has been already some length to establish the wakes. For a value of zero the source is right at the undulator start, while a negative value prevents any wake, till the interation position has passed that point.

genesis.version4.Write

Bases: NameList

With this name list the field or particle distributions are dumped. The placeholder character @ can be used to refer to the rootname of the simulation run, e.g. field = @.final

Write corresponds to Genesis 4 namelist write.

Attributes:

Name	Type	Description
field	str, default=""	if a filename is defined, Genesis writes out the field distribution of all harmonics. The harmonics are indicated by the suffix ’.hxxx.’ where xxx is the harmonic number. The filename gets the extension.fld.h5 automatically
beam	str, default=""	if a filename is defined, Genesis writes out the particle distribution. The filename gets the extension.par.h5 automatically
stride	int, default=1	For values larger than 1 the amount of particles written to the file is reduced by only writing each strideth particle to the dump file.