Element and Lattice

Element

An Element aggregates all data for a single lattice element: head metadata, general attributes, Twiss parameters, orbit, transfer matrix, floor coordinates, multipoles, wake fields, chamber walls, and more.

Data is loaded on-demand via from_tao() or fill(), controlled by defaults and per-field boolean flags. The class-level DEFAULTS set determines which fields are loaded when defaults=True.

pytao.model.Element

Bases: TaoBaseModel

Represents a Tao element with various attributes used in simulations.

Each attribute marked with a default value may be filled in or updated on-demand.

Attributes:

Name	Type	Description
ele_id	str	The element name or identifier.
which	"base", "model", or "design"
head	ElementHead	The head data of the element.
attrs	GeneralAttributes or None, default=None	General attributes associated with the element. The information held differs depending on the element's key (i.e., ele.head.key).
chamber_walls	list[ElementChamberWall] or None, default=None	List of chamber walls.
control_vars	dict[str, float] or None, default=None	Dictionary of control variables with their corresponding current values.
floor	ElementFloorAll or None, default=None	Floor positions.
grid_field	list[ElementGridField] or None, default=None	List of grid field data.
lord_slave	list[tao_classes.ElementLordSlave] or None, default=None	List of lord-slave relationships.
mat6	ElementMat6 or None, default=None	Mat6 (linear transfer map) information.
multipoles	AnyElementMultipoles or None, default=None	Multipoleattributes.
orbit	ElementOrbit or None, default=None	Orbit attributes.
photon	ElementPhoton or None, default=None	Photon attributes.
twiss	ElementTwiss or None, default=None	Twiss parameters.
wake	ElementWake or None, default=None	Wake attributes.
wall3d	list[ElementWall3D] or None, default=None	List of 3D walls.

Attributes

pytao.model.Element.attribs property

attribs

General attributes - name to value dictionary.

pytao.model.Element.id property

id

The fully-qualified ElementID, including universe/branch/key.

pytao.model.Element.symplectic_error property

symplectic_error

Symplectic error.

pytao.model.Element.vec0 property

vec0

0th order transport vector.

Functions

pytao.model.Element.fill

fill(tao, *, head=True, attrs=True, bunch_params=True, comb=False, control_vars=True, floor=True, lord_slave=True, photon=True, orbit=True, twiss=True, grid_field=True, grid_field_points=False, mat6=True, chamber_walls=True, wall3d=True, wall3d_table=False, multipoles=True, wake=True, comb_data=None, use_cache=True)

Fills various attributes of the Tao object based on the provided flags.

Parameters:

Name	Type	Description	Default
tao	Tao	The Tao instance to retrieve information from.	required
head	bool	Update the head attribute.	True
attrs	bool	Fill attribute data.	True
bunch_params	bool	Fill bunch parameters.	True
comb	bool or None	Fill comb data. If available, pass in comb_data as well to avoid querying Tao again for the full comb data.	False
comb_data	Comb or None	Only relevant if comb=True. If available, provide comb_data to avoid querying Tao again for the full comb data.	None
control_vars	bool	Fill control variables.	True
floor	bool	Fill the floor attribute.	True
lord_slave	bool	Fill lord-slave relationships.	True
photon	bool	Fill the photon attribute.	True
orbit	bool	Fill orbit data.	True
twiss	bool	Fill Twiss parameters.	True
grid_field	bool	Fill grid field data.	True
grid_field_points	bool	Fill grid field points data. Default is False.	False
mat6	bool	Fill MAT6 data.	True
chamber_walls	bool	Fill chamber wall data.	True
wall3d	bool	Fill 3D wall data.	True
wall3d_table	bool	Fill 3D wall table data. Default is False.	False
multipoles	bool	Fill multipole data.	True
wake	bool	Fill wake data.	True
use_cache	bool	use cached data if available. Will not overwrite already-fetched data.	True

Source code in pytao/model/ele/ele.py

def fill(
    self,
    tao: Tao,
    *,
    head: bool = True,
    attrs: bool = True,
    bunch_params: bool = True,
    comb: bool = False,
    control_vars: bool = True,
    floor: bool = True,
    lord_slave: bool = True,
    photon: bool = True,
    orbit: bool = True,
    twiss: bool = True,
    grid_field: bool = True,
    grid_field_points: bool = False,
    mat6: bool = True,
    chamber_walls: bool = True,
    wall3d: bool = True,
    wall3d_table: bool = False,
    multipoles: bool = True,
    wake: bool = True,
    # Others:
    comb_data: Comb | None = None,
    use_cache: bool = True,
):
    """
    Fills various attributes of the Tao object based on the provided flags.

    Parameters
    ----------
    tao : Tao
        The Tao instance to retrieve information from.
    head : bool, default=True
        Update the head attribute.
    attrs : bool, default=True
        Fill attribute data.
    bunch_params : bool, default=True
        Fill bunch parameters.
    comb : bool or None, default=False
        Fill comb data.  If available, pass in `comb_data` as well to avoid
        querying Tao again for the full comb data.
    comb_data : Comb or None, default=None
        Only relevant if `comb=True`.
        If available, provide `comb_data` to avoid querying Tao again for
        the full comb data.
    control_vars : bool, default=True
        Fill control variables.
    floor : bool, default=True
        Fill the floor attribute.
    lord_slave : bool, default=True
        Fill lord-slave relationships.
    photon : bool, default=True
        Fill the photon attribute.
    orbit : bool, default=True
        Fill orbit data.
    twiss : bool, default=True
        Fill Twiss parameters.
    grid_field : bool, default=True
        Fill grid field data.
    grid_field_points : bool, default=False
        Fill grid field points data. Default is False.
    mat6 : bool, default=True
        Fill MAT6 data.
    chamber_walls : bool, default=True
        Fill chamber wall data.
    wall3d : bool, default=True
        Fill 3D wall data.
    wall3d_table : bool, default=False
        Fill 3D wall table data. Default is False.
    multipoles : bool, default=True
        Fill multipole data.
    wake : bool, default=True
        Fill wake data.
    use_cache : bool, default=True
        use cached data if available.  Will not overwrite already-fetched
        data.
    """

    def should_update(obj):
        return obj is None or not use_cache

    if head and should_update(self.head):
        self._fill_head(tao)
    if attrs and should_update(self.attrs):
        self._fill_attrs(tao)
    if bunch_params and should_update(self.bunch_params):
        self._fill_bunch_params(tao)
    if comb and should_update(self.comb):
        self._fill_comb(tao, comb_data=comb_data)
    if control_vars and should_update(self.control_vars):
        self._fill_control_vars(tao)
    if floor and should_update(self.floor):
        self._fill_floor(tao)
    if lord_slave and should_update(self.lord_slave):
        self._fill_lord_slave(tao)
    if photon and should_update(self.photon):
        self._fill_photon(tao)
    if orbit and should_update(self.orbit):
        self._fill_orbit(tao)
    if twiss and should_update(self.twiss):
        self._fill_twiss(tao)
    if grid_field or grid_field_points:
        if self.grid_field is None:
            have_points = False
        else:
            have_points = any(fld.points is not None for fld in self.grid_field)
        if should_update(self.grid_field) or (not have_points and grid_field_points):
            self._fill_grid_field(tao, points=grid_field_points)
    if mat6 and should_update(self.mat6):
        self._fill_mat6(tao)
    if chamber_walls and should_update(self.chamber_walls):
        self._fill_chamber_walls(tao)
    if wall3d and should_update(self.wall3d):
        self._fill_wall3d(tao, fill_table=wall3d_table)
    if multipoles and should_update(self.multipoles):
        self._fill_multipoles(tao)
    if wake and should_update(self.wake):
        self._fill_wake(tao)

pytao.model.Element.from_tao classmethod

from_tao(tao, ele, *, which='model', defaults=True, attrs=FillDefault('attrs'), bunch_params=FillDefault('bunch_params'), chamber_walls=FillDefault('chamber_walls'), comb=FillDefault('comb'), control_vars=FillDefault('control_vars'), floor=FillDefault('floor'), grid_field=FillDefault('grid_field'), grid_field_points=FillDefault('grid_field_points'), lord_slave=FillDefault('lord_slave'), mat6=FillDefault('mat6'), multipoles=FillDefault('multipoles'), orbit=FillDefault('orbit'), photon=FillDefault('photon'), twiss=FillDefault('twiss'), wake=FillDefault('wake'), wall3d=FillDefault('wall3d'), wall3d_table=FillDefault('wall3d_table'), comb_data=None)

Create an Element by querying Tao.

Use defaults to fill the most commonly-used element information. To disregard the defaults, individual items may be excluded by passing False, or included by passing True.

Notes

Defaults for the data to query are set as follows:

from pytao.model import Element print(Element.DEFAULTS) {'attrs', 'bunch_params', 'chamber_walls', 'control_vars', 'floor', 'grid_field', 'lord_slave', 'mat6', 'multipoles', 'orbit', 'photon', 'twiss', 'wake', 'wall3d'}

With the following, the default will change to only query attrs:

Element.DEFAULTS = {"attrs"}

Examples:

Get an Element with the defaults (loads attrs, twiss, orbit, etc.):

>>> ele = Element.from_tao(tao, "1")

Get an Element but skip orbit calculations:

>>> ele = Element.from_tao(tao, "1", orbit=False)

Get an Element AND add comb data (usually off):

>>> ele = Element.from_tao(tao, "1", comb=True)

Get a minimal Element (disable everything explicit):

>>> ele = Element.from_tao(tao, "1", defaults=False)

Parameters:

Name	Type	Description	Default
tao	Tao	The Tao instance.	required
ele	int, str, or ElementID	The element identifier.	required
which	"base", "model", or "design"	Specifies which Tao lattice to use, by default "model".	'model'
defaults	bool	Fill default items. Defaults are set by name in Element.DEFAULTS.	True
attrs	bool	Fill general attributes.	FillDefault('attrs')
bunch_params	bool	Fill bunch parameters.	FillDefault('bunch_params')
chamber_walls	bool	Fill chamber wall data.	FillDefault('chamber_walls')
comb	bool	Fill comb data. If available, pass in comb_data as well to avoid querying Tao again for the full comb data.	False
comb_data	Comb or None	Only relevant if comb=True. If available, provide comb_data to avoid querying Tao again for the full comb data.	None
control_vars	bool	Fill control variables.	FillDefault('control_vars')
floor	bool	Fill floor data.	FillDefault('floor')
grid_field	bool	Fill grid field data.	FillDefault('grid_field')
grid_field_points	bool	Fill grid field points data.	False
lord_slave	bool	Fill lord-slave relationships.	FillDefault('lord_slave')
mat6	bool	Fill mat6 data.	FillDefault('mat6')
multipoles	bool	Fill multipole data.	FillDefault('multipoles')
orbit	bool	Fill orbit data.	FillDefault('orbit')
photon	bool	Fill photon data.	FillDefault('photon')
twiss	bool	Fill twiss parameters.	FillDefault('twiss')
wake	bool	Fill wake data.	FillDefault('wake')
wall3d	bool	Fill 3D wall data.	FillDefault('wall3d')
wall3d_table	bool	Fill 3D wall table data.	FillDefault('wall3d_table')

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao(
    cls,
    tao: Tao,
    ele: AnyElementID,
    *,
    which: Which = "model",
    defaults: bool = True,
    # Individually fillable elements:
    attrs: bool | FillDefault = FillDefault("attrs"),
    bunch_params: bool | FillDefault = FillDefault("bunch_params"),
    chamber_walls: bool | FillDefault = FillDefault("chamber_walls"),
    comb: bool | FillDefault = FillDefault("comb"),
    control_vars: bool | FillDefault = FillDefault("control_vars"),
    floor: bool | FillDefault = FillDefault("floor"),
    grid_field: bool | FillDefault = FillDefault("grid_field"),
    grid_field_points: bool | FillDefault = FillDefault("grid_field_points"),
    lord_slave: bool | FillDefault = FillDefault("lord_slave"),
    mat6: bool | FillDefault = FillDefault("mat6"),
    multipoles: bool | FillDefault = FillDefault("multipoles"),
    orbit: bool | FillDefault = FillDefault("orbit"),
    photon: bool | FillDefault = FillDefault("photon"),
    twiss: bool | FillDefault = FillDefault("twiss"),
    wake: bool | FillDefault = FillDefault("wake"),
    wall3d: bool | FillDefault = FillDefault("wall3d"),
    wall3d_table: bool | FillDefault = FillDefault("wall3d_table"),
    comb_data: Comb | None = None,
):
    """
    Create an `Element` by querying Tao.

    Use `defaults` to fill the most commonly-used element information.
    To disregard the defaults, individual items may be excluded by passing
    `False`, or included by passing `True`.

    Notes
    -----

    Defaults for the data to query are set as follows:

    >>> from pytao.model import Element
    >>> print(Element.DEFAULTS)
    {'attrs', 'bunch_params', 'chamber_walls', 'control_vars', 'floor',
    'grid_field', 'lord_slave', 'mat6', 'multipoles', 'orbit', 'photon',
    'twiss', 'wake', 'wall3d'}

    With the following, the default will change to only query `attrs`:

    >>> Element.DEFAULTS = {"attrs"}

    Examples
    --------

    Get an Element with the defaults (loads attrs, twiss, orbit, etc.):
    >>> ele = Element.from_tao(tao, "1")

    Get an Element but skip orbit calculations:
    >>> ele = Element.from_tao(tao, "1", orbit=False)

    Get an Element AND add comb data (usually off):
    >>> ele = Element.from_tao(tao, "1", comb=True)

    Get a minimal Element (disable everything explicit):
    >>> ele = Element.from_tao(tao, "1", defaults=False)

    Parameters
    ----------
    tao : Tao
        The Tao instance.
    ele : int, str, or ElementID
        The element identifier.
    which : "base", "model", or "design", optional
        Specifies which Tao lattice to use, by default "model".
    defaults : bool, default=True
        Fill default items.  Defaults are set by name in `Element.DEFAULTS`.
    attrs : bool, optional
        Fill general attributes.
    bunch_params : bool, optional
        Fill bunch parameters.
    chamber_walls : bool, optional
        Fill chamber wall data.
    comb : bool, default=False
        Fill comb data.  If available, pass in `comb_data` as well to avoid
        querying Tao again for the full comb data.
    comb_data : Comb or None, optional
        Only relevant if `comb=True`.
        If available, provide `comb_data` to avoid querying Tao again for
        the full comb data.
    control_vars : bool, optional
        Fill control variables.
    floor : bool, optional
        Fill floor data.
    grid_field : bool, optional
        Fill grid field data.
    grid_field_points : bool, default=False
        Fill grid field points data.
    lord_slave : bool, optional
        Fill lord-slave relationships.
    mat6 : bool, optional
        Fill mat6 data.
    multipoles : bool, optional
        Fill multipole data.
    orbit : bool, optional
        Fill orbit data.
    photon : bool, optional
        Fill photon data.
    twiss : bool, optional
        Fill twiss parameters.
    wake : bool, optional
        Fill wake data.
    wall3d : bool, optional
        Fill 3D wall data.
    wall3d_table : bool, optional
        Fill 3D wall table data.
    """
    ele = to_ele_id(ele)

    head = get_head(tao=tao, ele=ele, which=which)
    instance = cls(which=which, head=head, ele=ele)

    def should_fill(flag: bool | FillDefault):
        if flag is True or flag is False:
            return flag
        if not isinstance(flag, FillDefault):
            raise ValueError(f"Unexpected flag: {flag}")

        return defaults and (flag.attr in cls.DEFAULTS)

    instance.fill(
        tao,
        head=False,
        attrs=should_fill(attrs),
        bunch_params=should_fill(bunch_params),
        chamber_walls=should_fill(chamber_walls),
        control_vars=should_fill(control_vars),
        comb=should_fill(comb),
        floor=should_fill(floor),
        grid_field=should_fill(grid_field),
        grid_field_points=should_fill(grid_field_points),
        lord_slave=should_fill(lord_slave),
        mat6=should_fill(mat6),
        multipoles=should_fill(multipoles),
        orbit=should_fill(orbit),
        photon=should_fill(photon),
        twiss=should_fill(twiss),
        wake=should_fill(wake),
        wall3d=should_fill(wall3d),
        wall3d_table=should_fill(wall3d_table),
        comb_data=comb_data,
        use_cache=True,
    )
    return instance

Lattice

A Lattice is a tuple of Element objects with lookup dictionaries by name, key (element type), and index.

pytao.model.Lattice

Bases: TaoBaseModel

A Bmad Lattice, or more commonly a single branch of a full lattice.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
elements	tuple of Element	A tuple containing elements that make up the lattice.

Attributes

pytao.model.Lattice.by_element_index property

by_element_index

A dictionary of element index to Element.

pytao.model.Lattice.by_element_key property

by_element_key

A dictionary of element key to list of Elements with that key.

pytao.model.Lattice.by_element_name property

by_element_name

A dictionary of element name to Element.

Functions

pytao.model.Lattice.from_file classmethod

from_file(filename, *, format=None)

Load Tao model data from a previously-written file.

Parameters:

Name	Type	Description	Default
filename	str or Path		required

Returns:

Type	Description
Lattice

Source code in pytao/model/ele/ele.py

@classmethod
def from_file(
    cls,
    filename: str | pathlib.Path,
    *,
    format: ArchiveFormat | None = None,
) -> Self:
    """
    Load Tao model data from a previously-written file.

    Parameters
    ----------
    filename : str or pathlib.Path

    Returns
    -------
    Lattice
    """
    lat = super().from_file(filename, format=format)
    lat.filename = pathlib.Path(filename)
    return lat

pytao.model.Lattice.from_tao_eles classmethod

from_tao_eles(tao, eles, *, which='model', comb_data=None, comb=False, **kwargs)

Create a Lattice object from a list of element names, indices, or IDs.

Parameters:

Name	Type	Description	Default
tao	Tao		required
eles	list of int, str, or ElementID	Element names, indices, or identifiers.	required
which	"base", "model", or "design"		"model"
**kwargs	dict	Additional keyword arguments passed to Element.from_tao.	{}

Returns:

Type	Description
Lattice

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao_eles(
    cls,
    tao: Tao,
    eles: list[AnyElementID],
    *,
    which: Which = "model",
    comb_data: Comb | None = None,
    comb: bool = False,
    **kwargs,
):
    """
    Create a `Lattice` object from a list of element names, indices, or IDs.

    Parameters
    ----------
    tao : Tao
    eles : list of int, str, or ElementID
        Element names, indices, or identifiers.
    which : "base", "model", or "design", default="model"
    **kwargs : dict
        Additional keyword arguments passed to `Element.from_tao`.

    Returns
    -------
    Lattice
    """
    if comb and comb_data is None:
        # If 'comb' is specified for all elements, calculate it once ahead
        # of time.
        comb_data = Comb.from_tao(tao)
    elements = tuple(
        Element.from_tao(
            tao, ele=ele, which=which, comb=comb, comb_data=comb_data, **kwargs
        )
        for ele in eles
    )
    return cls(
        which=which,
        elements=elements,
    )

pytao.model.Lattice.from_tao_tracking classmethod

from_tao_tracking(tao, *, track_start=None, track_end=None, which='model', orbit=True, twiss=True, ix_branch='', ix_uni='', **kwargs)

Create a Lattice object from tracking elements of the lattice.

Parameters:

Name	Type	Description	Default
tao	Tao		required
which	"base", "model", or "design"		"model"
track_start	str	The first element to get information from (inclusive). Defaults to element 0.	None
track_end	str	The last element to get information from (inclusive). Defaults to the last element in the lattice.	None
orbit	bool	Orbit information is included by default.	True
twiss	bool	Twiss information is included by default.	True
ix_branch	str	Branch index, by default ""	''
ix_uni	str	Universe index, by default ""	''
**kwargs	dict	Additional keyword arguments passed to Element.from_tao.	{}

Returns:

Type	Description
Lattice

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao_tracking(
    cls,
    tao: Tao,
    *,
    track_start: ElementID | str | int | None = None,
    track_end: ElementID | str | int | None = None,
    which: Which = "model",
    orbit: bool = True,
    twiss: bool = True,
    ix_branch: str = "",
    ix_uni: str = "",
    **kwargs,
):
    """
    Create a `Lattice` object from tracking elements of the lattice.

    Parameters
    ----------
    tao : Tao
    which : "base", "model", or "design", default="model"
    track_start : str, optional
        The first element to get information from (inclusive).  Defaults to
        element 0.
    track_end : str, optional
        The last element to get information from (inclusive).  Defaults to
        the last element in the lattice.
    orbit : bool, default=True
        Orbit information is included by default.
    twiss : bool, default=True
        Twiss information is included by default.
    ix_branch : str, optional
        Branch index, by default ""
    ix_uni : str, optional
        Universe index, by default ""
    **kwargs : dict
        Additional keyword arguments passed to `Element.from_tao`.

    Returns
    -------
    Lattice
    """

    indices: list[int] = [
        int(idx)
        for idx in cast(
            list,
            tao.lat_list(
                "*", "ele.ix_ele", flags="-track_only", ix_branch=ix_branch, ix_uni=ix_uni
            ),
        )
    ]
    ix_start = get_element_index(tao, track_start) if track_start else 0
    ix_end = get_element_index(tao, track_end) if track_end else max(indices)
    return cls.from_tao_eles(
        tao=tao,
        eles=[ix_ele for ix_ele in indices if ix_start <= ix_ele <= ix_end],
        which=which,
        orbit=orbit,
        twiss=twiss,
        **kwargs,
    )

pytao.model.Lattice.from_tao_unique classmethod

from_tao_unique(tao, *, which='model', track_start=None, track_end=None, ix_branch='', ix_uni='', **kwargs)

Create a Lattice object from unique elements of the lattice.

Parameters:

Name	Type	Description	Default
tao	Tao		required
which	"base", "model", or "design"		"model"
track_start	str	The first element to get information from (inclusive). Defaults to element 0. This does not need to be a unique element itself.	None
track_end	str	The last element to get information from (inclusive). Defaults to the last element in the lattice. This does not need to be a unique element itself.	None
ix_branch	str	Branch index, by default ""	''
ix_uni	str	Universe index, by default ""	''
**kwargs	dict	Additional keyword arguments passed to Element.from_tao.	{}

Returns:

Type	Description
Lattice

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao_unique(
    cls,
    tao: Tao,
    *,
    which: Which = "model",
    track_start: ElementID | str | int | None = None,
    track_end: ElementID | str | int | None = None,
    ix_branch: str = "",
    ix_uni: str = "",
    **kwargs,
):
    """
    Create a `Lattice` object from unique elements of the lattice.

    Parameters
    ----------
    tao : Tao
    which : "base", "model", or "design", default="model"
    track_start : str, optional
        The first element to get information from (inclusive).  Defaults to
        element 0.
        This does not need to be a unique element itself.
    track_end : str, optional
        The last element to get information from (inclusive).  Defaults to
        the last element in the lattice.
        This does not need to be a unique element itself.
    ix_branch : str, optional
        Branch index, by default ""
    ix_uni : str, optional
        Universe index, by default ""
    **kwargs : dict
        Additional keyword arguments passed to `Element.from_tao`.

    Returns
    -------
    Lattice
    """
    indices: list[int] = [
        int(idx)
        for idx in cast(
            list,
            tao.lat_list(
                "*", "ele.ix_ele", flags="-no_slaves", ix_branch=ix_branch, ix_uni=ix_uni
            ),
        )
    ]
    ix_start = get_element_index(tao, track_start) if track_start else 0
    ix_end = get_element_index(tao, track_end) if track_end else max(indices)
    return cls.from_tao_eles(
        tao=tao,
        eles=[ix_ele for ix_ele in indices if ix_start <= ix_ele <= ix_end],
        which=which,
        **kwargs,
    )

ElementID

Parses and represents Tao's element identifier syntax, including universe, branch, key, name, match number, and offset.

pytao.model.ElementID

Bases: BaseModel

An element identifier, which breaks apart a Tao element identifier into its components.

An element "name" (which can match to multiple elements) in Tao can be of the form

{~}{uni@}{branch>>}{key::}ele_id{##N}{+/-offset}

where

Syntax	Description
~	Negation character. See below.
key	Optional key name ("quadrupole", "sbend", etc.)
uni	Index of universe.
branch	Name or index of branch. May contain the wild cards * and %.
ele_id	Name or index of element. May contain the wild cards * and %.
	If a name and no branch is given, all branches are searched.
	If an index and no branch is given, branch 0 is assumed.
##N	N = integer. N^th instance of ele_id in the branch.
+/-offset	Element offset. For example, Q1+1 is the element after Q1 and Q1-2 is the second element
	before Q1. Modulo arithmetic is used so the offset wraps around the ends of the lattice.
	EG: BEGINNING-1 gives the END element and END+1 gives the BEGINNING element.

Note: An old syntax that is still supported is:

{key::}{branch>>}ele_id{##N}

An element range is of the form:

{key::}ele1:ele2

Where the range includes ele1 and ele2, and:

Parameter	Description
key	Optional key name ("quadrupole", "sbend", etc.). Also key may be "type", "alias", or "descrip"
	in which case the %type, %alias, or %descrip field is matched to instead of the element name.
ele1	Starting element of the range.
ele2	Ending element of the range.

Attributes

pytao.model.ElementID.tao_string property

tao_string

This element represented in Tao command-line interface string form.

pytao.model.ElementID.without_universe property

without_universe

This element ID, excluding the universe number.

Some Tao commands such as 'show lat' do not accept a universe number.

Returns:

Type	Description
ElementID

Functions

pytao.model.ElementID.from_tao classmethod

from_tao(value)

Construct an ElementID from the Tao string representation.

Parameters:

Name	Type	Description	Default
value	str		required

Returns:

Type	Description
ElementID

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao(cls, value: str) -> ElementID:
    """
    Construct an ElementID from the Tao string representation.

    Parameters
    ----------
    value : str

    Returns
    -------
    ElementID
    """
    if "," in value:
        raise ValueError(
            f"Comma (',') found in the identifier {value!r}.  This indicates multiple elements. "
            f"Use `.from_tao_any` instead."
        )
    if "&" in value:
        raise ValueError(
            f"Ampersand ('&') found in the identifier {value!r}.  This indicates the intersection of multiple elements. "
            f"Use `.from_tao_any` instead."
        )

    value = value.strip()

    if not value:
        raise EmptyElementNameError("No element name specified")

    ele_id = None
    key = None
    universe = None
    branch = None

    match_number = None
    match_offset = None
    negated = False

    if "@" not in value and "::" in value and ">>" in value:
        if value.index("::") < value.index(">>"):
            return cls.from_tao_old_syntax(value)
    remaining = value

    def split_next(delim: str) -> tuple[str, str] | tuple[None, str]:
        if delim in remaining:
            return remaining.split(delim, 1)
        return None, remaining

    # Universe prefix *first*, then negation, then branch/key (mirroring
    # lat_ele_locator).
    universe, remaining = split_next("@")

    if remaining.startswith("~"):
        negated = True
        remaining = remaining[1:]

    branch, remaining = split_next(">>")
    key, remaining = split_next("::")

    if "##" in remaining:
        ele_id, match_number = split_next("##")

        if "+" in match_number:
            match_number, match_offset = match_number.split("+")
            match_offset = int(match_offset)
        elif "-" in match_number:
            match_number, match_offset = match_number.split("-")
            match_offset = -int(match_offset)

        match_number = int(match_number)
        assert match_offset is None or isinstance(match_offset, int)
    elif "+" in remaining:
        ele_id, match_offset = split_next("+")
        match_offset = int(match_offset)
        remaining = ""
    elif "-" in remaining:
        ele_id, match_offset = split_next("-")
        match_offset = -int(match_offset)
        remaining = ""
    else:
        ele_id, remaining = remaining, ""

    branch = _maybe_int(branch)
    universe = _maybe_int(universe)
    if match_number is not None:
        match_number = int(match_number)

    if ele_id is None:
        raise ValueError("No element ID found in the string")

    return cls(
        ele_id=ele_id,
        key=key,
        universe=universe,
        branch=branch,
        match_number=match_number,
        match_offset=match_offset,
        negated=negated,
    )

pytao.model.ElementID.from_tao_any classmethod

from_tao_any(value, *, split_range=False)

Create the most appropriate instance of an Element class for the given Tao element string.

Parameters:

Name	Type	Description	Default
value	str	A string representing an element identifier, a list of elements, or an intersection of elements.	required

Returns:

Type	Description
ElementID, ElementList, or ElementIntersection

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao_any(
    cls, value: str, *, split_range: bool = False
) -> ElementID | ElementList | ElementIntersection | ElementRange:
    """
    Create the most appropriate instance of an Element class for the given
    Tao element string.

    Parameters
    ----------
    value : str
        A string representing an element identifier, a list of elements, or
        an intersection of elements.

    Returns
    -------
    ElementID, ElementList, or ElementIntersection
    """
    if "," in value:
        return ElementList.from_tao(value)
    if split_range and ":" in value.replace("::", " "):
        return ElementRange.from_tao(value)
    if "&" in value:
        return ElementIntersection.from_tao(value)
    return cls.from_tao(value)

pytao.model.ElementID.from_tao_old_syntax classmethod

from_tao_old_syntax(value)

Convert a Tao old syntax Element identifier.

Parameters:

Name	Type	Description	Default
value	str		required

Returns:

Type	Description
ElementID

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao_old_syntax(cls, value: str) -> ElementID:
    """
    Convert a Tao old syntax Element identifier.

    Parameters
    ----------
    value : str

    Returns
    -------
    ElementID
    """
    ele_id = None
    key = None
    universe = None
    branch = None

    match_number = None
    match_offset = None
    negated = False

    if not value.strip():
        raise EmptyElementNameError("No element name specified")

    if "::" in value and ">>" in value:
        assert value.index("::") < value.index(">>")

    remaining = value

    def split_next(delim: str) -> tuple[str | None, str]:
        if delim in remaining:
            return remaining.split(delim, 1)
        return None, remaining

    key, remaining = split_next("::")
    branch, remaining = split_next(">>")

    if "##" in remaining:
        ele_id, match_number = split_next("##")
    else:
        ele_id = remaining

    branch = _maybe_int(branch)
    if match_number is not None:
        match_number = int(match_number)

    if ele_id is None:
        raise ValueError("No element ID found in the string")

    return cls(
        ele_id=ele_id,
        key=key,
        universe=universe,
        branch=branch,
        match_number=match_number,
        match_offset=match_offset,
        negated=negated,
    )

GeneralAttributes

Dynamic container for element-type-specific attributes (e.g., L, K1, angle). Supports case-insensitive access. Each attribute is an Attr with name, data, units, type, and a settable flag.

pytao.model.GeneralAttributes

Bases: TaoModel

Element Sub-Models

These are the data classes that populate the fields of Element.

ElementHead

pytao.model.ElementHead

Bases: TaoModel

Structure which corresponds to Tao pipe ele:head 1, for example.

Attributes:

Name	Type	Description
alias	str	Another name.
descrip	str	Description string.
has_ab_multipoles	bool
has_ac_kick	bool
has_control	bool
has_floor	bool
has_kt_multipoles	bool
has_lord_slave	bool
has_mat6	bool
has_methods	bool
has_multipoles_elec	bool
has_photon	bool
has_spin_taylor	bool
has_taylor	bool
has_twiss	bool
has_wake	bool
has_wall3d	int
is_on	bool	For turning element on/off.
ix_branch	int	Index in lat%branch(:) array. Note: lat%ele => lat%branch(0).
ix_ele	int	Index in branch ele(0:) array. Set to ix_slice_slave$ = -2 for
slice_slave$ elements.
key	str	Element class (quadrupole, etc.).
name	str	name of element.
num_cartesian_map	int
num_cylindrical_map	int
num_gen_grad_map	int
num_grid_field	int
ref_time	float	Time ref particle passes exit end.
s	float	longitudinal ref position at the exit end.
s_start	float	longitudinal ref position at entrance_end
type	str	type name.
universe	int

ElementTwiss

pytao.model.ElementTwiss

Bases: TaoModel

Structure which corresponds to Tao pipe ele:twiss 1, for example.

Attributes:

Name	Type	Description
alpha_a	float
alpha_b	float
beta_a	float
beta_b	float
dalpha_dpz_a	float
dalpha_dpz_b	float
dbeta_dpz_a	float
dbeta_dpz_b	float
deta_dpz_a	float
deta_dpz_b	float
deta_dpz_x	float
deta_dpz_y	float
deta_ds_a	float
deta_ds_b	float
deta_dsx	float
deta_dsy	float
detap_dpz_a	float
detap_dpz_b	float
detap_dpz_x	float
detap_dpz_y	float
eta_a	float
eta_b	float
eta_x	float
eta_y	float
etap_a	float
etap_b	float
etap_x	float
etap_y	float
gamma_a	float
gamma_b	float
mode_flip	bool
phi_a	float
phi_b	float

ElementOrbit

pytao.model.ElementOrbit

Bases: TaoModel

Structure which corresponds to Tao pipe ele:orbit 1, for example.

Attributes:

Name	Type	Description
beta	float	Velocity / c_light.
charge	float	Macroparticle weight (which is different from particle species
charge). For some space charge calcs the weight is in Coulombs.
direction	int	+1 or -1. Sign of longitudinal direction of motion (ds/dt). This is
independent of the element orientation.
dt_ref	float	Used in: * time tracking for computing z. * by coherent photons =
path_length/c_light.
field	sequence of floats	Photon E-field intensity (x,y).
ix_ele	int	Index of the lattice element the particle is in. May be -1 if element
is not associated with a lattice.
location	str	upstream_end$, inside$, or downstream_end$
p0c	float	For non-photons: Reference momentum. For photons: Photon momentum (not
reference).
phase	sequence of floats	Photon E-field phase (x,y). For charged particles, phase(1) is RF
phase.
px	float
py	float
pz	float
s	float	Longitudinal position
species	str	positron$, proton$, etc.
spin	sequence of floats	Spin.
state	str	alive$, lost$, lost_neg_x_aperture$, lost_pz$, etc.
t	float	Absolute time (not relative to reference). Note: Quad precision!
x	float
y	float
z	float

ElementMat6

pytao.model.ElementMat6

Bases: TaoModel

Linear transfer map (mat6) data.

Attributes:

Name	Type	Description
mat6	NDArray of shape (6, 6)
vec0	NDArray
symplectic_error	float

ElementFloorAll

pytao.model.ElementFloorAll

Bases: TaoBaseModel

Element floor positions based on optical trajectory - at its beginning, center, or end.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
beginning	ElementFloor	The element position at the beginning.
center	ElementFloor	The element position at its center.
end	ElementFloor	The element position at its end.

ElementFloor

pytao.model.ElementFloor

Bases: TaoBaseModel

Represents the floor position of an element.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
where	"beginning", "center", or "end"	The location or placement of the element on the floor.
actual	(ElementFloorPosition, optional)	The actual position of the element on the floor.
reference	(ElementFloorPosition, optional)	The reference position of the element on the floor.
slaves	dict[int, ElementFloorItem]	A mapping of integer slave numbers to ElementFloorItem instances.

ElementFloorPosition

pytao.model.ElementFloorPosition

Bases: TaoBaseModel

Represents the position and orientation of an element on the floor in a 3D space.

Attributes:

Name	Type	Description
x	float, default 0.0	The x-coordinate of the position.
y	float, default 0.0	The y-coordinate of the position.
z	float, default 0.0	The z-coordinate of the position.
theta	float, default 0.0	The rotation around the x-axis in radians.
phi	float, default 0.0	The rotation around the y-axis in radians.
psi	float, default 0.0	The rotation around the z-axis in radians.
wmat	list of list of float, default empty list	The transformation matrix representing the orientation of the element.

ElementBunchParams

pytao.model.ElementBunchParams

Bases: TaoModel

Structure which corresponds to Tao pipe bunch_params 1, for example.

Attributes:

Name	Type	Description
beam_saved	bool
centroid_beta	float
centroid_p0c	float
centroid_t	float
centroid_vec_1	float
centroid_vec_2	float
centroid_vec_3	float
centroid_vec_4	float
centroid_vec_5	float
centroid_vec_6	float
charge_live	float	Charge of all non-lost particle
direction	int
ix_ele	int	Lattice element where params evaluated at.
location	str	Location in element: upstream_end$, inside$, or downstream_end$
n_particle_live	int	Number of non-lost particles
n_particle_lost_in_ele	int	Number lost in element (not calculated by Bmad)
n_particle_tot	int	Total number of particles
rel_max_1	float
rel_max_2	float
rel_max_3	float
rel_max_4	float
rel_max_5	float
rel_max_6	float
rel_min_1	float
rel_min_2	float
rel_min_3	float
rel_min_4	float
rel_min_5	float
rel_min_6	float
s	float	Longitudinal position.
sigma_11	float
sigma_12	float
sigma_13	float
sigma_14	float
sigma_15	float
sigma_16	float
sigma_21	float
sigma_22	float
sigma_23	float
sigma_24	float
sigma_25	float
sigma_26	float
sigma_31	float
sigma_32	float
sigma_33	float
sigma_34	float
sigma_35	float
sigma_36	float
sigma_41	float
sigma_42	float
sigma_43	float
sigma_44	float
sigma_45	float
sigma_46	float
sigma_51	float
sigma_52	float
sigma_53	float
sigma_54	float
sigma_55	float
sigma_56	float
sigma_61	float
sigma_62	float
sigma_63	float
sigma_64	float
sigma_65	float
sigma_66	float
sigma_t	float	RMS of time spread.
species	str
t	float	Time.
twiss_alpha_a	float
twiss_alpha_b	float
twiss_alpha_c	float
twiss_alpha_x	float
twiss_alpha_y	float
twiss_alpha_z	float
twiss_beta_a	float
twiss_beta_b	float
twiss_beta_c	float
twiss_beta_x	float
twiss_beta_y	float
twiss_beta_z	float
twiss_dalpha_dpz_a	float
twiss_dalpha_dpz_b	float
twiss_dalpha_dpz_c	float
twiss_dalpha_dpz_x	float
twiss_dalpha_dpz_y	float
twiss_dalpha_dpz_z	float
twiss_dbeta_dpz_a	float
twiss_dbeta_dpz_b	float
twiss_dbeta_dpz_c	float
twiss_dbeta_dpz_x	float
twiss_dbeta_dpz_y	float
twiss_dbeta_dpz_z	float
twiss_deta_dpz_a	float
twiss_deta_dpz_b	float
twiss_deta_dpz_c	float
twiss_deta_dpz_x	float
twiss_deta_dpz_y	float
twiss_deta_dpz_z	float
twiss_deta_ds_a	float
twiss_deta_ds_b	float
twiss_deta_ds_c	float
twiss_deta_ds_x	float
twiss_deta_ds_y	float
twiss_deta_ds_z	float
twiss_detap_dpz_a	float
twiss_detap_dpz_b	float
twiss_detap_dpz_c	float
twiss_detap_dpz_x	float
twiss_detap_dpz_y	float
twiss_detap_dpz_z	float
twiss_emit_a	float
twiss_emit_b	float
twiss_emit_c	float
twiss_emit_x	float
twiss_emit_y	float
twiss_emit_z	float
twiss_eta_a	float
twiss_eta_b	float
twiss_eta_c	float
twiss_eta_x	float
twiss_eta_y	float
twiss_eta_z	float
twiss_etap_a	float
twiss_etap_b	float
twiss_etap_c	float
twiss_etap_x	float
twiss_etap_y	float
twiss_etap_z	float
twiss_gamma_a	float
twiss_gamma_b	float
twiss_gamma_c	float
twiss_gamma_x	float
twiss_gamma_y	float
twiss_gamma_z	float
twiss_norm_emit_a	float
twiss_norm_emit_b	float
twiss_norm_emit_c	float
twiss_norm_emit_x	float
twiss_norm_emit_y	float
twiss_norm_emit_z	float
twiss_phi_a	float
twiss_phi_b	float
twiss_phi_c	float
twiss_phi_x	float
twiss_phi_y	float
twiss_phi_z	float
twiss_sigma_a	float
twiss_sigma_b	float
twiss_sigma_c	float
twiss_sigma_p_a	float
twiss_sigma_p_b	float
twiss_sigma_p_c	float
twiss_sigma_p_x	float
twiss_sigma_p_y	float
twiss_sigma_p_z	float
twiss_sigma_x	float
twiss_sigma_y	float
twiss_sigma_z	float

ElementMultipoles

pytao.model.ElementMultipoles

Bases: TaoModel

Structure which corresponds to Tao pipe ele:multipoles 13, for example.

Attributes:

Name	Type	Description
data	ElementMultipoles_Data	Structure which corresponds to Tao pipe ele:multipoles 13, for
example.
multipoles_on	bool	For turning multipoles on/off
scale_multipoles	bool or None	Are ab_multipoles within other elements (EG: quads, etc.) scaled by
the strength of the element?

ElementPhoton

pytao.model.ElementPhoton

Bases: ElementPhotonBase

Class representing a element's photon details.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
has_material	bool	Whether material is present or None.
has_pixel	bool	Whether pixel is present or None.
curvature	ElementPhotonCurvature	Curvature of the photon element.
material	ElementPhotonMaterial	Material properties of the photon element.

ElementWake

pytao.model.ElementWake

Bases: ElementWakeBase

ElementWall3D

pytao.model.ElementWall3D

Bases: ElementWall3DBase

ElementWall3D class representing a 3D wall element in a lattice.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
index	int	The index of the wall element.
table	list of ElementWall3DTable or None, optional	A table containing wall element details.

ElementChamberWall

pytao.model.ElementChamberWall

Bases: TaoBaseModel

Represents a chamber wall element in the lattice.

Attributes:

Name	Type	Description
which	"base", "model", or "design"
index	int	The index of the chamber wall of the element.
x	list of ElementChamberWall	A list of ElementChamberWall objects along the x-axis.
y	list of ElementChamberWall	A list of ElementChamberWall objects along the y-axis.

ElementLordSlave

pytao.model.ElementLordSlave

Bases: TaoModel

Structure which corresponds to Tao pipe ele:lord_slave 1 1 x, for example.

Attributes:

Name	Type	Description
key	str
location_name	str
name	str
status	str
type	str

ElementGridField

pytao.model.ElementGridField

Bases: ElementGridField

Comb

Cumulative bunch moment data across the lattice.

pytao.model.Comb

Bases: TaoModel

Functions

pytao.model.Comb.from_tao classmethod

from_tao(tao, *, check_ds_save=True, ix_branch=0, **kwargs)

Create a Comb instance from Tao.

Parameters:

Name	Type	Description	Default
tao	Tao		required
ix_branch	int		0
**kwargs	dict	Additional keyword arguments to pass to comb_data_from_tao.	{}

Returns:

Type	Description
Comb

Source code in pytao/model/ele/comb.py

@classmethod
def from_tao(
    cls: type[Self], tao: Tao, *, check_ds_save: bool = True, ix_branch: int = 0, **kwargs
) -> Self:
    """
    Create a Comb instance from Tao.

    Parameters
    ----------
    tao : Tao

    ix_branch : int, optional

    **kwargs : dict
        Additional keyword arguments to pass to `comb_data_from_tao`.

    Returns
    -------
    Comb
    """
    if check_ds_save:
        if tao.beam(ix_branch)["ds_save"] <= 0:
            return cls()

    return cls(**comb_data_from_tao(tao, ix_branch=ix_branch, **kwargs))

pytao.model.Comb.slice_by_s

slice_by_s(s_start, s_end, *, inclusive=True)

Slice the Comb data by 's' position between specified start and end values.

Parameters:

Name	Type	Description	Default
s_start	float	The starting s value of the slice.	required
s_end	float	The ending s value of the slice.	required
inclusive	bool	If True, the slice includes s_start and s_end. Otherwise, it excludes these boundaries.	True

Returns:

Type	Description
Comb	A new instance of the Comb class with the sliced data.

Source code in pytao/model/ele/comb.py

def slice_by_s(self, s_start: float, s_end: float, *, inclusive: bool = True) -> Comb:
    """
    Slice the Comb data by 's' position between specified start and end values.

    Parameters
    ----------
    s_start : float
        The starting s value of the slice.
    s_end : float
        The ending s value of the slice.
    inclusive : bool, default=True
        If True, the slice includes `s_start` and `s_end`.
        Otherwise, it excludes these boundaries.

    Returns
    -------
    Comb
        A new instance of the Comb class with the sliced data.
    """
    s = np.asarray(self.s)
    if inclusive:
        (indices,) = np.where((s <= s_end) & (s >= s_start))
    else:
        (indices,) = np.where((s < s_end) & (s > s_start))

    def fix_value(value):
        if isinstance(value, (list, np.ndarray)):
            return np.asarray(value)[indices]
        return value

    data = {key: fix_value(value) for key, value in self.model_dump().items()}
    return type(self)(**data)

Helper Types

ElementRange

pytao.model.ElementRange

Bases: BaseModel

Multiple Tao elements.

Attributes

pytao.model.ElementRange.tao_string property

tao_string

This element list represented in Tao command-line interface string form.

Functions

pytao.model.ElementRange.from_tao classmethod

from_tao(value)

Convert a Tao representation of comma-delimited elements to an ElementList.

Parameters:

Name	Type	Description	Default
value	str		required

Returns:

Type	Description
ElementList or ElementRange

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao(cls, value: str) -> ElementRange:
    """
    Convert a Tao representation of comma-delimited elements to an
    ElementList.

    Parameters
    ----------
    value : str

    Returns
    -------
    ElementList or ElementRange
    """
    if ":" not in value:
        raise ValueError(f"No colon delimiter found in element identifier {value!r}")

    ele_id = ElementID.from_tao(value)
    ele1, ele2 = ele_id.ele_id.split(":")

    common = ele_id.model_dump()
    common.pop("ele_id")

    return cls(
        start=ElementID(ele_id=ele1, **common),
        end=ElementID(ele_id=ele2, **common),
    )

ElementList

pytao.model.ElementList

Bases: BaseModel

Multiple Tao elements.

Attributes

pytao.model.ElementList.tao_string property

tao_string

This element list represented in Tao command-line interface string form.

Functions

pytao.model.ElementList.from_tao classmethod

from_tao(value)

Convert a Tao representation of comma-delimited elements to an ElementList.

Parameters:

Name	Type	Description	Default
value	str		required

Returns:

Type	Description
ElementList

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao(cls, value: str) -> ElementList:
    """
    Convert a Tao representation of comma-delimited elements to an
    ElementList.

    Parameters
    ----------
    value : str

    Returns
    -------
    ElementList
    """
    if "," not in value:
        raise ValueError(f"No comma delimiter found in element identifier {value!r}")
    return cls(elements=tuple(ElementID.from_tao(part) for part in value.split(",")))

ElementIntersection

pytao.model.ElementIntersection

Bases: BaseModel

An intersection of multiple Tao elements.

Attributes

pytao.model.ElementIntersection.tao_string property

tao_string

This element intersection represented in Tao command-line interface string form.

Functions

pytao.model.ElementIntersection.from_tao classmethod

from_tao(value)

Create an ElementIntersection instance from a Tao format, ampersand-delimited string.

Parameters:

Name	Type	Description	Default
value	str		required

Returns:

Type	Description
ElementIntersection

Source code in pytao/model/ele/ele.py

@classmethod
def from_tao(cls, value: str) -> ElementIntersection:
    """
    Create an ElementIntersection instance from a Tao format, ampersand-delimited string.

    Parameters
    ----------
    value : str

    Returns
    -------
    ElementIntersection
    """
    if "&" not in value:
        raise ValueError("No intersection found in element identifier {value!r}")
    return cls(elements=tuple(ElementID.from_tao(part) for part in value.split("&")))