Tao

pytao.Tao

Tao(init='', so_lib='', *, plot='tao', beam_file=None, beam_init_position_file=None, building_wall_file=None, command='', data_file=None, debug=False, disable_smooth_line_calc=False, external_plotting=False, geometry='', hook_init_file=None, init_file=None, lattice_file=None, log_startup=False, no_stopping=False, noinit=False, noplot=False, nostartup=False, no_rad_int=False, plot_file=None, prompt_color='', reverse=False, rf_on=False, quiet=False, slice_lattice='', start_branch_at='', startup_file=None, symbol_import=False, var_file=None)

Bases: _TaoAutogeneratedCommandMixin, TaoCore

Communicate with Tao using ctypes.

Parameters:

Name	Type	Description	Default
`init`	`str`	Initialization string for Tao. Same as the tao command-line, including "-init" and such. Shell variables in `init` strings will be expanded by Tao. For example, an `init` string containing `$HOME` would be replaced by your home directory.	`''`
`so_lib`	`str`	Path to the Tao shared library. Auto-detected if not specified.	`''`
`plot`	`(str, bool)`	Use pytao's plotting mechanism with matplotlib or bokeh, if available. If `True`, pytao will pick an appropriate plotting backend. If `False` or "tao", Tao plotting will be used. (Default) If "mpl", the pytao matplotlib plotting backend will be selected. If "bokeh", the pytao Bokeh plotting backend will be selected.	`'tao'`
`beam_file`	`str or Path`	File containing the tao_beam_init namelist.	`None`
`beam_init_position_file`	`Path or str`	File containing initial particle positions.	`None`
`building_wall_file`	`str or Path`	Define the building tunnel wall	`None`
`command`	`str`	Commands to run after startup file commands	`''`
`data_file`	`str or Path`	Define data for plotting and optimization	`None`
`debug`	`bool`	Debug mode for Wizards	`False`
`disable_smooth_line_calc`	`bool`	Disable the smooth line calc used in plotting	`False`
`external_plotting`	`bool`	Tells Tao that plotting is done externally to Tao.	`False`
`geometry`	`"wxh" or (width, height) tuple`	Plot window geometry (pixels)	`''`
`hook_init_file`	`pathlib.Path or str`	Init file for hook routines (Default = tao_hook.init)	`None`
`init_file`	`str or Path`	Tao init file	`None`
`lattice_file`	`str or Path`	Bmad lattice file	`None`
`log_startup`	`bool`	Write startup debugging info	`False`
`no_stopping`	`bool`	For debugging : Prevents Tao from exiting on errors	`False`
`noinit`	`bool`	Do not use Tao init file.	`False`
`noplot`	`bool`	Do not open a plotting window	`False`
`nostartup`	`bool`	Do not open a startup command file	`False`
`no_rad_int`	`bool`	Do not do any radiation integrals calculations.	`False`
`plot_file`	`str or Path`	Plotting initialization file	`None`
`prompt_color`	`str`	Set color of prompt string. Default is blue.	`''`
`reverse`	`bool`	Reverse lattice element order?	`False`
`rf_on`	`bool`	Use "--rf_on" to turn off RF (default is now RF on)	`False`
`quiet`	`bool`	Suppress terminal output when running a command file?	`False`
`slice_lattice`	`str`	Discards elements from lattice that are not in the list	`''`
`start_branch_at`	`str`	Start lattice branch at element.	`''`
`startup_file`	`str or Path`	Commands to run after parsing Tao init file	`None`
`symbol_import`	`bool`	Import symbols defined in lattice files(s)?	`False`
`var_file`	`str or Path`	Define variables for plotting and optimization	`None`

Attributes:

Name	Type	Description
`plot_backend_name`	`str or None`	Plotting backend name, if using pytao plotting. `None` indicates that internal Tao plotting is to be used. Changing the backend may require reinitialization to enable external plotting.
`init_output`	`list of str`	Tao initialization output, recorded when the Tao object first initializes. Subsequent calls to `init()` will override this variable.

Source code in pytao/tao.py

@override
def __init__(
    self,
    init: str = "",
    so_lib: str = "",
    *,
    plot: str | bool = "tao",
    beam_file: AnyPath | None = None,
    beam_init_position_file: AnyPath | None = None,
    building_wall_file: AnyPath | None = None,
    command: str = "",
    data_file: AnyPath | None = None,
    debug: bool = False,
    disable_smooth_line_calc: bool = False,
    external_plotting: bool = False,
    geometry: str | tuple[int, int] = "",
    hook_init_file: AnyPath | None = None,
    init_file: AnyPath | None = None,
    lattice_file: AnyPath | None = None,
    log_startup: bool = False,
    no_stopping: bool = False,
    noinit: bool = False,
    noplot: bool = False,
    nostartup: bool = False,
    no_rad_int: bool = False,
    plot_file: AnyPath | None = None,
    prompt_color: str = "",
    reverse: bool = False,
    rf_on: bool = False,
    quiet: bool = False,
    slice_lattice: str = "",
    start_branch_at: str = "",
    startup_file: AnyPath | None = None,
    symbol_import: bool = False,
    var_file: AnyPath | None = None,
):
    self._init_shared_library(so_lib=so_lib)
    self.plot_backend_name = None
    self._graph_managers = {}
    self._tao_version_checked = False
    self.init(
        cmd=init,
        plot=plot,
        beam_file=beam_file,
        beam_init_position_file=beam_init_position_file,
        building_wall_file=building_wall_file,
        command=command,
        data_file=data_file,
        debug=debug,
        disable_smooth_line_calc=disable_smooth_line_calc,
        external_plotting=external_plotting,
        geometry=geometry,
        hook_init_file=hook_init_file,
        init_file=init_file,
        lattice_file=lattice_file,
        log_startup=log_startup,
        no_stopping=no_stopping,
        noinit=noinit,
        noplot=noplot,
        nostartup=nostartup,
        no_rad_int=no_rad_int,
        plot_file=plot_file,
        prompt_color=prompt_color,
        reverse=reverse,
        rf_on=rf_on,
        quiet=quiet,
        slice_lattice=slice_lattice,
        start_branch_at=start_branch_at,
        startup_file=startup_file,
        symbol_import=symbol_import,
        var_file=var_file,
    )
    try:
        self.register_cell_magic()
    except NameError:
        # Not in IPython
        pass
    except Exception:
        logger.debug("Failed to register cell magic", exc_info=True)

Attributes

pytao.Tao.bokeh `property`

bokeh

Get the Bokeh graph manager.

pytao.Tao.matplotlib `property`

matplotlib

Get the Matplotlib graph manager.

pytao.Tao.plot_manager `property`

plot_manager

The currently-configured plot graph manager.

This can be configured at initialization time by specifying plot="mpl", for example. This may also be reconfigured by changing the attribute plot_backend_name.

Functions

pytao.Tao.archive

archive(directory, prefix='run_tao', *, mkdir=True, lat_name=None, shebang='/usr/bin/env bash', tao_binary='tao')

Write the state of Tao to be reloaded in a PyTao session.

This writes: * The currently loaded lattice (via write bmad) * TaoConfig settings - BmadCom, SpaceChargeCom, BeamInit, Beam, and globals. * A shell script (.sh) that executes Tao with the lattice and config file

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Directory where the generated scripts will be saved.	required
`prefix`	`str`	Filename prefix for the generated scripts. By default "run_tao".	`'run_tao'`
`mkdir`	`bool`	If True, creates the directory and its parents if they do not exist. By default True.	`True`
`lat_name`	`str or None`	The lattice filename to write, if `tao` is specified. Defaults to `"{prefix}.lat.bmad"`.	`None`
`tao_binary`	`str`	The Tao binary to use. This may also be set to "pytao" to utilize PyTao's command-line entrypoint.	`'tao'`

Returns:

Type	Description
`tuple[Path, Path]`	A tuple containing the paths to the generated bash shell script (`sh_file`) and the Tao command file (`cmd_file`).

Source code in pytao/tao.py

def archive(
    self,
    directory: pathlib.Path | str,
    prefix: str = "run_tao",
    *,
    mkdir: bool = True,
    lat_name: str | None = None,
    shebang: str = "/usr/bin/env bash",
    tao_binary: str = "tao",
) -> tuple[pathlib.Path, pathlib.Path]:
    """
    Write the state of Tao to be reloaded in a PyTao session.

    This writes:
    * The currently loaded lattice (via `write bmad`)
    * TaoConfig settings - BmadCom, SpaceChargeCom, BeamInit, Beam, and globals.
    * A shell script (.sh) that executes Tao with the lattice and config file

    Parameters
    ----------
    directory : pathlib.Path
        Directory where the generated scripts will be saved.
    prefix : str, optional
        Filename prefix for the generated scripts. By default "run_tao".
    mkdir : bool, optional
        If True, creates the directory and its parents if they do not exist.
        By default True.
    lat_name : str or None, optional
        The lattice filename to write, if `tao` is specified.
        Defaults to ``"{prefix}.lat.bmad"``.
    tao_binary : str, optional
        The Tao binary to use.  This may also be set to "pytao" to utilize
        PyTao's command-line entrypoint.

    Returns
    -------
    tuple[pathlib.Path, pathlib.Path]
        A tuple containing the paths to the generated bash shell script
        (`sh_file`) and the Tao command file (`cmd_file`).
    """
    config = self.get_config()
    return config.write_bash_loader_script(
        directory=directory,
        prefix=prefix,
        mkdir=mkdir,
        lat_name=lat_name,
        shebang=shebang,
        tao=self,
        tao_binary=tao_binary,
    )

pytao.Tao.bunch_data

bunch_data(ele_id, *, which='model', ix_bunch=1, verbose=False)

Returns bunch data in openPMD-beamphysics format/notation.

Notes

Note that Tao's 'write beam' will also write a proper h5 file in this format.

Expected usage: data = bunch_data(tao, 'end') from beamphysics import ParticleGroup P = ParicleGroup(data=data)

Returns:

Name	Type	Description
`data`	`dict`	dict of arrays, with keys 'x', 'px', 'y', 'py', 't', 'pz', 'status', 'weight', 'z', 'species'

Examples:

Example: 1 init: $ACC_ROOT_DIR/tao/examples/csr_beam_tracking/tao.init args: ele_id: end which: model ix_bunch: 1

Source code in pytao/tao.py

def bunch_data(self, ele_id, *, which="model", ix_bunch=1, verbose=False):
    """
    Returns bunch data in openPMD-beamphysics format/notation.

    Notes
    -----
    Note that Tao's 'write beam' will also write a proper h5 file in this format.

    Expected usage:
        data = bunch_data(tao, 'end')
        from beamphysics import ParticleGroup
        P = ParicleGroup(data=data)


    Returns
    -------
    data : dict
        dict of arrays, with keys 'x', 'px', 'y', 'py', 't', 'pz',
        'status', 'weight', 'z', 'species'


    Examples
    --------
    Example: 1
    init: $ACC_ROOT_DIR/tao/examples/csr_beam_tracking/tao.init
    args:
    ele_id: end
    which: model
    ix_bunch: 1

    """

    # Get species
    stats = self.bunch_params(ele_id, which=which, verbose=verbose)
    species = stats["species"]

    dat = {}
    for coordinate in ["x", "px", "y", "py", "t", "pz", "p0c", "charge", "state"]:
        dat[coordinate] = self.bunch1(
            ele_id,
            coordinate=coordinate,
            which=which,
            ix_bunch=ix_bunch,
            verbose=verbose,
        )

    # Remove normalizations
    p0c = dat.pop("p0c")

    dat["status"] = dat.pop("state")
    dat["weight"] = dat.pop("charge")

    # px from Bmad is px/p0c
    # pz from Bmad is delta = p/p0c -1.
    # pz = sqrt( (delta+1)**2 -px**2 -py**2)*p0c
    dat["pz"] = np.sqrt((dat["pz"] + 1) ** 2 - dat["px"] ** 2 - dat["py"] ** 2) * p0c
    dat["px"] = dat["px"] * p0c
    dat["py"] = dat["py"] * p0c

    # z = 0 by definition
    dat["z"] = np.full(len(dat["x"]), 0)

    dat["species"] = species.lower()

    return dat

pytao.Tao.cmds

cmds(cmds, suppress_lattice_calc=True, suppress_plotting=True, raises=True)

Runs a list of commands, optionally suppressing lattice calculations and plotting updates.

Parameters:

Name	Type	Description	Default
`cmds`	`list of str`	List of string commands.	required
`suppress_lattice_calc`	`bool`	Suppress lattice calc when applying the commands.	`True`
`suppress_plotting`		Suppress plotting when applying commands.	`True`
`raises`	`bool`	Raise an exception of [ERROR or [FATAL is detected in the output.	`True`

Returns:

Type	Description
`list`	Results corresponding to the commands

Source code in pytao/tao.py

def cmds(self, cmds, suppress_lattice_calc=True, suppress_plotting=True, raises=True):
    """
    Runs a list of commands, optionally suppressing lattice calculations
    and plotting updates.

    Parameters
    ----------
    cmds : list of str
        List of string commands.
    suppress_lattice_calc : bool, default=True
        Suppress lattice calc when applying the commands.
    suppress_plotting  : bool, default=True
        Suppress plotting when applying commands.
    raises : bool, default=True
        Raise an exception of [ERROR or [FATAL is detected in the output.

    Returns
    -------
    list
        Results corresponding to the commands

    """
    # Get globals to detect plotting
    g = self.tao_global()
    ploton, laton = g["plot_on"], g["lattice_calc_on"]

    if suppress_plotting and ploton:
        self.cmd("set global plot_on = F")
    if suppress_lattice_calc and laton:
        self.cmd("set global lattice_calc_on = F")

    # Actually apply commands
    results = []
    for cmd in cmds:
        res = self.cmd(cmd, raises=raises)
        results.append(res)

    if suppress_plotting and ploton:
        self.cmd("set global plot_on = T")
    if suppress_lattice_calc and laton:
        self.cmd("set global lattice_calc_on = T")

    return results

pytao.Tao.ele

ele(ele_id, ix_uni='1', ix_branch='0', *, which='model', defaults=True, warn=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)

Get a single Element instance by querying Tao.

Note See Tao.eles for more usage information.

Examples:

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

>>> ele = tao.eles("Q1")

Do not warn if Q1 matches more than one element:

>>> ele = tao.eles("Q1", warn=False)

Get an Element but skip orbit calculations:

>>> ele = tao.eles("Q1", orbit=False)

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

>>> ele = tao.eles("Q1", comb=True)

Get a minimal Element (disable everything explicit):

>>> ele = tao.eles("Q1", defaults=False)

Parameters:

Name	Type	Description	Default
`ele_id`	`int, str, or ElementID`	The element identifier or match string. Tao supports many different ways to refer to elements. See the notes sections for more details.	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/tao.py

def ele(
    self,
    ele_id: AnyElementID,
    ix_uni: str = "1",
    ix_branch: str = "0",
    *,
    which: Which = "model",
    defaults: bool = True,
    warn: 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,
) -> Element:
    """
    Get a single `Element` instance by querying Tao.

    **Note** See `Tao.eles` for more usage information.

    Examples
    --------

    Get a single Element with the defaults (loads attrs, twiss, orbit, etc.):
    >>> ele = tao.eles("Q1")

    Do not warn if Q1 matches more than one element:
    >>> ele = tao.eles("Q1", warn=False)

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

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

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

    Parameters
    ----------
    ele_id : int, str, or ElementID
        The element identifier or match string.
        Tao supports many different ways to refer to elements. See the
        notes sections for more details.
    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.
    """

    ids = [
        ElementID(universe=int(ix_uni), branch=ix_branch, ele_id=str(ix_ele))
        for ix_ele in cast(
            Sequence[str],
            self.lat_list(
                str(ele_id),
                who="ele.ix_ele",
                ix_uni=ix_uni,
                ix_branch=ix_branch,
                which=which,
                flags="-array_out",
            ),
        )
    ]

    if not ids:
        raise ElementNotFoundError("No matching element found")
    if len(ids) > 1 and warn:
        logger.warning(
            f"More than one element found matching {ele_id!r}. Returning the first one. "
            f"To suppress this, use `warn=False`."
        )

    id_ = ids[0]
    return Element.from_tao(
        self,
        id_,
        defaults=defaults,
        attrs=attrs,
        bunch_params=bunch_params,
        chamber_walls=chamber_walls,
        comb=comb,
        control_vars=control_vars,
        floor=floor,
        grid_field=grid_field,
        grid_field_points=grid_field_points,
        lord_slave=lord_slave,
        mat6=mat6,
        multipoles=multipoles,
        orbit=orbit,
        photon=photon,
        twiss=twiss,
        wake=wake,
        wall3d=wall3d,
        wall3d_table=wall3d_table,
        comb_data=comb_data,
    )

pytao.Tao.eles

eles(ele_id=None, ix_uni='1', ix_branch='0', *, 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)

Get one or more Element instances 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

Speed

For large lattices, querying a lot of data may take a long time. If you find that this method takes too long for your purposes and you do not need all of the data it supplies, you can change the defaults (as in the section below) or opt-out of individual settings on a per-call basis (by using False).

Defaults

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"}

Element IDs

This section is only a brief overview of ways to refer to elements or ranges of elements in Tao. See the Tao manual for further details.

By name: * Q1 (elements matching Q1 in the current universe)

By partial match (glob): * Q1* (elements starting with "Q1")

By numerical identifier: * 1 (element 1 of the default/current universe)

Full universe, branch, element ID: * 1@0>>1 (universe 1, branch 0, element 1)

By range: * 1:2 (elements 1 and 2 of the default universe) * 2>>1:2 (elements 1 and 2 of branch 2 in the default universe) * 1@2>>1:2 (elements 1 and 2 of branch 2 in universe 1)

By key: * sbend::s1 (element named "s1" that has a key SBEND) * sbend::s1:s3 (elements between SBEND "s1" to "s3", inclusive) * marker::m1##2 (the element 2 elements after marker 'm1') * type::bpm* (elements with a type that starts with "bpm")

Examples:

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

>>> ele, = tao.eles("1")

Get an Element but skip orbit calculations:

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

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

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

Get a minimal Element (disable everything explicit):

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

Get a range of Elements with the default settings:

>>> ele1, ele2 = tao.eles("1:2")

Get a range of Elements with the default settings:

>>> s1_through_s3 = tao.eles("sbend::s1:s3")

Get all of the quads with the default settings:

>>> quads = tao.eles("quad::*")

Parameters:

Name	Type	Description	Default
`ele_id`	`int, str, ElementID, or sequence of these`	The element identifier or match string. Tao supports many different ways to refer to elements. See the notes sections for more details.	`None`
`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/tao.py

def eles(
    self,
    ele_id: AnyElementID | Sequence[AnyElementID] | None = None,
    ix_uni: str = "1",
    ix_branch: str = "0",
    *,
    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,
) -> list[Element]:
    """
    Get one or more `Element` instances 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
    -----

    **Speed**

    For large lattices, querying a lot of data may take a long time.
    If you find that this method takes too long for your purposes
    and you do not need all of the data it supplies, you can change
    the defaults (as in the section below) or opt-out of individual
    settings on a per-call basis (by using `False`).

    **Defaults**

    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"}

    **Element IDs**

    This section is only a brief overview of ways to refer to elements
    or ranges of elements in Tao. See the Tao manual for further details.

    By name:
    * Q1 (elements matching Q1 in the current universe)

    By partial match (glob):
    * Q1* (elements starting with "Q1")

    By numerical identifier:
    * 1 (element 1 of the default/current universe)

    Full universe, branch, element ID:
    * 1@0>>1 (universe 1, branch 0, element 1)

    By range:
    * 1:2  (elements 1 and 2 of the default universe)
    * 2>>1:2  (elements 1 and 2 of branch 2 in the default universe)
    * 1@2>>1:2  (elements 1 and 2 of branch 2 in universe 1)

    By key:
    * sbend::s1  (element named "s1" that has a key SBEND)
    * sbend::s1:s3  (elements between SBEND "s1" to "s3", inclusive)
    * marker::m1##2  (the element 2 elements after marker 'm1')
    * type::bpm*  (elements with a type that starts with "bpm")

    Examples
    --------

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

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

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

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

    Get a range of Elements with the default settings:
    >>> ele1, ele2 = tao.eles("1:2")

    Get a range of Elements with the default settings:
    >>> s1_through_s3 = tao.eles("sbend::s1:s3")

    Get all of the quads with the default settings:
    >>> quads = tao.eles("quad::*")

    Parameters
    ----------
    ele_id : int, str, ElementID, or sequence of these
        The element identifier or match string.
        Tao supports many different ways to refer to elements. See the
        notes sections for more details.
    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.
    """
    if not ele_id:
        ids = self.unique_ele_ids_from_superuniverse()
    else:
        ids = []
        if isinstance(ele_id, (str, int, ElementID)):
            ele_id = [ele_id]

        for id1 in ele_id:
            ids.extend(
                [
                    ElementID(universe=int(ix_uni), branch=ix_branch, ele_id=str(ix_ele))
                    for ix_ele in cast(
                        Sequence[str],
                        self.lat_list(
                            str(id1),
                            who="ele.ix_ele",
                            ix_uni=ix_uni,
                            ix_branch=ix_branch,
                            which=which,
                            flags="-array_out",
                        ),
                    )
                ]
            )

    return [
        Element.from_tao(
            self,
            id_,
            defaults=defaults,
            attrs=attrs,
            bunch_params=bunch_params,
            chamber_walls=chamber_walls,
            comb=comb,
            control_vars=control_vars,
            floor=floor,
            grid_field=grid_field,
            grid_field_points=grid_field_points,
            lord_slave=lord_slave,
            mat6=mat6,
            multipoles=multipoles,
            orbit=orbit,
            photon=photon,
            twiss=twiss,
            wake=wake,
            wall3d=wall3d,
            wall3d_table=wall3d_table,
            comb_data=comb_data,
        )
        for id_ in ids
    ]

pytao.Tao.from_lattice_contents `classmethod`

from_lattice_contents(contents, **kwargs)

Initialize the Tao instance using its Bmad format lattice contents.

Parameters:

Name	Type	Description	Default
`contents`	`str`	The Bmad-format lattice file contents (i.e., not a filename).	required
`**kwargs`		See `Tao` for other initialization keyword arguments. All except `lattice_file` are allowed.	`{}`

Source code in pytao/tao.py

@classmethod
def from_lattice_contents(cls, contents: str, **kwargs):
    """
    Initialize the Tao instance using its Bmad format lattice contents.

    Parameters
    ----------
    contents : str, optional
        The Bmad-format lattice file contents (i.e., not a filename).
    **kwargs :
        See `Tao` for other initialization keyword arguments. All except
        `lattice_file` are allowed.
    """
    if "lattice_file" in kwargs:
        raise ValueError("'lattice_file' is not allowed")

    with NamedTemporaryFile("wt") as fp:
        print(contents, file=fp)
        fp.flush()
        return cls(lattice_file=fp.name, **kwargs)

pytao.Tao.get_active_beam_track_element

get_active_beam_track_element()

Get the active element index being tracked.

Thread-safe and intended to be used by UIs to determine which element is currently being tracked.

Source code in pytao/tao.py

def get_active_beam_track_element(self) -> int:
    """
    Get the active element index being tracked.

    Thread-safe and intended to be used by UIs to determine which element
    is currently being tracked.
    """
    return self.so_lib.tao_c_get_beam_track_element()

pytao.Tao.get_config

get_config(ix_uni='', ix_branch='', **kwargs)

Get a configuration object representing the state of Tao.

Parameters:

Name	Type	Description	Default
`ix_branch`	`str`	Branch index, by default ""	`''`
`ix_uni`	`str`	Universe index, by default ""	`''`

Returns:

Type	Description
`TaoConfig`

Source code in pytao/tao.py

def get_config(self, ix_uni: str = "", ix_branch: str = "", **kwargs) -> TaoConfig:
    """
    Get a configuration object representing the state of Tao.

    Parameters
    ----------
    ix_branch : str, optional
        Branch index, by default ""
    ix_uni : str, optional
        Universe index, by default ""

    Returns
    -------
    TaoConfig
    """
    return TaoConfig.from_tao(self, ix_uni=ix_uni, ix_branch=ix_branch, **kwargs)

pytao.Tao.init

init(cmd='', *, plot='tao', beam_file=None, beam_init_position_file=None, building_wall_file=None, command='', data_file=None, debug=False, disable_smooth_line_calc=False, external_plotting=False, geometry='', hook_init_file=None, init_file=None, lattice_file=None, log_startup=False, no_stopping=False, noinit=False, noplot=False, nostartup=False, no_rad_int=False, plot_file=None, prompt_color='', reverse=False, rf_on=False, quiet=False, slice_lattice='', start_branch_at='', startup_file=None, symbol_import=False, var_file=None)

(Re-)Initialize Tao with the given command.

Parameters:

Name	Type	Description	Default
`cmd`	`str`	Initialization string for Tao. Same as the tao command-line, including "-init" and such. Shell variables in `init` strings will be expanded by Tao. For example, an `init` string containing `$HOME` would be replaced by your home directory.	`''`
`plot`	`(str, bool)`	Use pytao's plotting mechanism with matplotlib or bokeh, if available. If `True`, pytao will pick an appropriate plotting backend. If `False` or "tao", Tao plotting will be used. (Default) If "mpl", the pytao matplotlib plotting backend will be selected. If "bokeh", the pytao Bokeh plotting backend will be selected.	`'tao'`
`beam_file`	`str or Path`	File containing the tao_beam_init namelist.	`None`
`beam_init_position_file`	`Path or str`	File containing initial particle positions.	`None`
`building_wall_file`	`str or Path`	Define the building tunnel wall	`None`
`command`	`str`	Commands to run after startup file commands	`''`
`data_file`	`str or Path`	Define data for plotting and optimization	`None`
`debug`	`bool`	Debug mode for Wizards	`False`
`disable_smooth_line_calc`	`bool`	Disable the smooth line calc used in plotting	`False`
`external_plotting`	`bool`	Tells Tao that plotting is done externally to Tao.	`False`
`geometry`	`"wxh" or (width, height) tuple`	Plot window geometry (pixels)	`''`
`hook_init_file`	`pathlib.Path or str`	Init file for hook routines (Default = tao_hook.init)	`None`
`init_file`	`str or Path`	Tao init file	`None`
`lattice_file`	`str or Path`	Bmad lattice file	`None`
`log_startup`	`bool`	Write startup debugging info	`False`
`no_stopping`	`bool`	For debugging : Prevents Tao from exiting on errors	`False`
`noinit`	`bool`	Do not use Tao init file.	`False`
`noplot`	`bool`	Do not open a plotting window	`False`
`nostartup`	`bool`	Do not open a startup command file	`False`
`no_rad_int`	`bool`	Do not do any radiation integrals calculations.	`False`
`plot_file`	`str or Path`	Plotting initialization file	`None`
`prompt_color`	`str`	Set color of prompt string. Default is blue.	`''`
`reverse`	`bool`	Reverse lattice element order?	`False`
`rf_on`	`bool`	Use "--rf_on" to turn off RF (default is now RF on)	`False`
`quiet`	`bool`	Suppress terminal output when running a command file?	`False`
`slice_lattice`	`str`	Discards elements from lattice that are not in the list	`''`
`start_branch_at`	`str`	Start lattice branch at element.	`''`
`startup_file`	`str or Path`	Commands to run after parsing Tao init file	`None`
`symbol_import`	`bool`	Import symbols defined in lattice files(s)?	`False`
`var_file`	`str or Path`	Define variables for plotting and optimization	`None`

Returns:

Type	Description
`list of str`	Tao's initialization output.

Source code in pytao/tao.py

def init(
    self,
    cmd: str = "",
    *,
    plot: str | bool = "tao",
    beam_file: AnyPath | None = None,
    beam_init_position_file: AnyPath | None = None,
    building_wall_file: AnyPath | None = None,
    command: str = "",
    data_file: AnyPath | None = None,
    debug: bool = False,
    disable_smooth_line_calc: bool = False,
    external_plotting: bool = False,
    geometry: str | tuple[int, int] = "",
    hook_init_file: AnyPath | None = None,
    init_file: AnyPath | None = None,
    lattice_file: AnyPath | None = None,
    log_startup: bool = False,
    no_stopping: bool = False,
    noinit: bool = False,
    noplot: bool = False,
    nostartup: bool = False,
    no_rad_int: bool = False,
    plot_file: AnyPath | None = None,
    prompt_color: str = "",
    reverse: bool = False,
    rf_on: bool = False,
    quiet: bool = False,
    slice_lattice: str = "",
    start_branch_at: str = "",
    startup_file: AnyPath | None = None,
    symbol_import: bool = False,
    var_file: AnyPath | None = None,
) -> list[str]:
    """
    (Re-)Initialize Tao with the given command.

    Parameters
    ----------
    cmd : str, optional
        Initialization string for Tao.  Same as the tao command-line, including
        "-init" and such.  Shell variables in `init` strings will be expanded
        by Tao.  For example, an `init` string containing `$HOME` would be
        replaced by your home directory.
    plot : str, bool, optional
        Use pytao's plotting mechanism with matplotlib or bokeh, if available.
        If `True`, pytao will pick an appropriate plotting backend.
        If `False` or "tao", Tao plotting will be used. (Default)
        If "mpl", the pytao matplotlib plotting backend will be selected.
        If "bokeh", the pytao Bokeh plotting backend will be selected.

    beam_file : str or pathlib.Path, default=None
        File containing the tao_beam_init namelist.
    beam_init_position_file : pathlib.Path or str, default=None
        File containing initial particle positions.
    building_wall_file : str or pathlib.Path, default=None
        Define the building tunnel wall
    command : str, optional
        Commands to run after startup file commands
    data_file : str or pathlib.Path, default=None
        Define data for plotting and optimization
    debug : bool, default=False
        Debug mode for Wizards
    disable_smooth_line_calc : bool, default=False
        Disable the smooth line calc used in plotting
    external_plotting : bool, default=False
        Tells Tao that plotting is done externally to Tao.
    geometry : "wxh" or (width, height) tuple, optional
        Plot window geometry (pixels)
    hook_init_file :  pathlib.Path or str, default=None
        Init file for hook routines (Default = tao_hook.init)
    init_file : str or pathlib.Path, default=None
        Tao init file
    lattice_file : str or pathlib.Path, default=None
        Bmad lattice file
    log_startup : bool, default=False
        Write startup debugging info
    no_stopping : bool, default=False
        For debugging : Prevents Tao from exiting on errors
    noinit : bool, default=False
        Do not use Tao init file.
    noplot : bool, default=False
        Do not open a plotting window
    nostartup : bool, default=False
        Do not open a startup command file
    no_rad_int : bool, default=False
        Do not do any radiation integrals calculations.
    plot_file : str or pathlib.Path, default=None
        Plotting initialization file
    prompt_color : str, optional
        Set color of prompt string. Default is blue.
    reverse : bool, default=False
        Reverse lattice element order?
    rf_on : bool, default=False
        Use "--rf_on" to turn off RF (default is now RF on)
    quiet : bool, default=False
        Suppress terminal output when running a command file?
    slice_lattice : str, optional
        Discards elements from lattice that are not in the list
    start_branch_at : str, optional
        Start lattice branch at element.
    startup_file : str or pathlib.Path, default=None
        Commands to run after parsing Tao init file
    symbol_import : bool, default=False
        Import symbols defined in lattice files(s)?
    var_file : str or pathlib.Path, default=None
        Define variables for plotting and optimization

    Returns
    -------
    list of str
        Tao's initialization output.
    """
    if plot in {"mpl", "bokeh"}:
        self.plot_backend_name = plot
    else:
        self.plot_backend_name = None

    use_pytao_plotting = plot in {"mpl", "bokeh", True}

    self.init_settings = TaoStartup(
        init=cmd,
        plot=plot,
        beam_file=beam_file,
        beam_init_position_file=beam_init_position_file,
        building_wall_file=building_wall_file,
        command=command,
        data_file=data_file,
        debug=debug,
        disable_smooth_line_calc=disable_smooth_line_calc,
        external_plotting=use_pytao_plotting or external_plotting,
        geometry=geometry,
        hook_init_file=hook_init_file,
        init_file=init_file,
        lattice_file=lattice_file,
        log_startup=log_startup,
        no_stopping=no_stopping,
        noinit=noinit,
        noplot=use_pytao_plotting or noplot,
        nostartup=nostartup,
        no_rad_int=no_rad_int,
        plot_file=plot_file,
        prompt_color=prompt_color,
        reverse=reverse,
        rf_on=rf_on,
        quiet=quiet,
        slice_lattice=slice_lattice,
        start_branch_at=start_branch_at,
        startup_file=startup_file,
        symbol_import=symbol_import,
        var_file=var_file,
    )

    default_tao_init = "tao.init"
    if not self.init_settings.can_initialize and pathlib.Path(default_tao_init).exists():
        # Can't initialize unless -lat or -init are specified.
        self.init_settings.init_file = default_tao_init

    if not self.init_settings.can_initialize:
        raise TaoInvalidArgumentsError(
            f"Tao will not be able to initialize with the following settings:"
            f"\n"
            f"\ninit={self.init_settings.tao_init!r}"
            f"\n"
            f"\nIn order to initialize a Tao object, you must specify at least one of these:"
            f"\n * `init_file` with a valid filename"
            f"\n * `lattice_file` with a valid filename"
            f"\n"
            f"\nFor example:"
            f"\n>>> Tao(init_file='$ACC_ROOT_DIR/bmad-doc/tao_examples/erl/tao.init')"
            f"\n"
            f"\nAlternatively, you may pass the full command-line arguments:"
            f"\n>>> Tao('-lat $ACC_ROOT_DIR/bmad-doc/tao_examples/erl/bmad.lat')"
        )

    self._init_output = self._init_backend(self.init_settings)
    if not self._tao_version_checked:
        self._tao_version_checked = True
        self._check_tao_version()
    return self._init_output

pytao.Tao.particles

particles(ele_id, *, which='model', ix_bunch=1, verbose=False)

Returns bunch data as an openPMD-beamphysics ParticleGroup.

Notes

Note that Tao's 'write beam' will also write a proper h5 file in this format.

Returns:

Type	Description
`ParticleGroup`

Source code in pytao/tao.py

def particles(self, ele_id, *, which="model", ix_bunch=1, verbose=False) -> ParticleGroup:
    """
    Returns bunch data as an openPMD-beamphysics ParticleGroup.

    Notes
    -----
    Note that Tao's `'write beam'` will also write a proper h5 file in this format.

    Returns
    -------
    ParticleGroup
    """

    P = ParticleGroup(
        data=self.bunch_data(
            ele_id=ele_id, which=which, ix_bunch=ix_bunch, verbose=verbose
        )
    )
    if len(P) == 0:
        raise ValueError(f"No particles saved for element: {ele_id}")
    return P

pytao.Tao.plot

plot(template=None, *, region_name=None, include_layout=True, width=None, height=None, layout_height=None, share_x=None, backend=None, grid=None, **kwargs)

Make a plot with the provided backend.

Plot a graph, or all placed graphs.

To plot a specific graph, specify template (optionally region_name). The default is to plot all placed graphs.

For full details on available parameters, see the specific backend's graph manager. For example:

In [1]: tao.bokeh.plot? In [2]: tao.matplotlib.plot?

Parameters:

Name	Type	Description	Default
`template`	`str or list[str]`	Graph template name or names.	`None`
`region_name`	`str`	Graph region name. Chosen automatically if not specified.	`None`
`include_layout`	`bool`	Include a layout plot at the bottom, if not already placed and if appropriate (i.e., another plot uses longitudinal coordinates on the x-axis).	`True`
`width`	`int`	Width of each plot.	`None`
`height`	`int`	Height of each plot.	`None`
`layout_height`	`int`	Height of the layout plot.	`None`
`share_x`	`bool or None`	Share x-axes where sensible (`None`) or force sharing x-axes (True) for all plots.	`None`
`save`	`Path or str`	Save the plot to the given filename.	required
`xlim`	`(float, float)`	X axis limits.	required
`ylim`	`(float, float)`	Y axis limits.	required
`grid`	`(nrows, ncols)`	If multiple graph names are specified, the plots will be placed in a grid according to this parameter. The default is to have stacked plots if this parameter is unspecified.	`None`
`backend`	`('bokeh', 'mpl')`	The backend to use. Auto-detects Jupyter and availability of bokeh to select a backend.	`"bokeh"`

Returns:

Type	Description
`None`	To gain access to the resulting plot objects, use the backend's `plot` method directly.

Source code in pytao/tao.py

def plot(
    self,
    template: str | list[str] | None = None,
    *,
    region_name: str | None = None,
    include_layout: bool = True,
    width: int | None = None,
    height: int | None = None,
    layout_height: int | None = None,
    share_x: bool | None = None,
    backend: str | None = None,
    grid: tuple[int, int] | None = None,
    **kwargs,
) -> None:
    """
    Make a plot with the provided backend.

    Plot a graph, or all placed graphs.

    To plot a specific graph, specify `template` (optionally `region_name`).
    The default is to plot all placed graphs.

    For full details on available parameters, see the specific backend's
    graph manager. For example:

    In [1]: tao.bokeh.plot?
    In [2]: tao.matplotlib.plot?

    Parameters
    ----------
    template : str or list[str]
        Graph template name or names.
    region_name : str, optional
        Graph region name.  Chosen automatically if not specified.
    include_layout : bool, optional
        Include a layout plot at the bottom, if not already placed and if
        appropriate (i.e., another plot uses longitudinal coordinates on
        the x-axis).
    width : int, optional
        Width of each plot.
    height : int, optional
        Height of each plot.
    layout_height : int, optional
        Height of the layout plot.
    share_x : bool or None, default=None
        Share x-axes where sensible (`None`) or force sharing x-axes (True)
        for all plots.
    save : pathlib.Path or str, optional
        Save the plot to the given filename.
    xlim : (float, float), optional
        X axis limits.
    ylim : (float, float), optional
        Y axis limits.
    grid : (nrows, ncols), optional
        If multiple graph names are specified, the plots will be placed
        in a grid according to this parameter.  The default is to have
        stacked plots if this parameter is unspecified.
    backend : {"bokeh", "mpl"}, optional
        The backend to use.  Auto-detects Jupyter and availability of bokeh
        to select a backend.

    Returns
    -------
    None
        To gain access to the resulting plot objects, use the backend's
        `plot` method directly.
    """
    manager = self._get_user_specified_backend(backend)

    if width is not None:
        kwargs["width"] = width
    if height is not None:
        kwargs["height"] = height
    if layout_height is not None:
        kwargs["layout_height"] = layout_height
    if share_x is not None:
        kwargs["share_x"] = share_x

    if not template:
        self.last_plot = manager.plot_all(
            include_layout=include_layout,
            **kwargs,
        )
    elif not isinstance(template, str):
        templates = list(template)
        grid = grid or (len(templates), 1)
        self.last_plot = manager.plot_grid(
            templates=templates,
            grid=grid,
            include_layout=include_layout,
            **kwargs,
        )
    else:
        self.last_plot = manager.plot(
            region_name=region_name,
            template=template,
            include_layout=include_layout,
            **kwargs,
        )

pytao.Tao.plot_field

plot_field(ele_id, *, colormap=None, radius=0.015, num_points=100, backend=None, **kwargs)

Plot field information for a given element.

Parameters:

Name	Type	Description	Default
`ele_id`	`str`	Element ID.	required
`colormap`	`str`	Colormap for the plot. Matplotlib defaults to "PRGn_r", and bokeh defaults to "Magma256".	`None`
`radius`	`float`	Radius.	`0.015`
`num_points`	`int`	Number of data points.	`100`
`backend`	`('bokeh', 'mpl')`	The backend to use. Auto-detects Jupyter and availability of bokeh to select a backend.	`"bokeh"`

Source code in pytao/tao.py

def plot_field(
    self,
    ele_id: str,
    *,
    colormap: str | None = None,
    radius: float = 0.015,
    num_points: int = 100,
    backend: str | None = None,
    **kwargs,
):
    """
    Plot field information for a given element.

    Parameters
    ----------
    ele_id : str
        Element ID.
    colormap : str, optional
        Colormap for the plot.
        Matplotlib defaults to "PRGn_r", and bokeh defaults to "Magma256".
    radius : float, default=0.015
        Radius.
    num_points : int, default=100
        Number of data points.
    backend : {"bokeh", "mpl"}, optional
        The backend to use.  Auto-detects Jupyter and availability of bokeh
        to select a backend.
    """
    manager = self._get_user_specified_backend(backend)
    self.last_plot = manager.plot_field(
        ele_id,
        colormap=colormap,
        radius=radius,
        num_points=num_points,
        **kwargs,
    )

pytao.Tao.plot_page

plot_page()

Get plot page parameters.

Source code in pytao/tao.py

def plot_page(self):
    """Get plot page parameters."""
    cmd = "show plot_page"
    return _pytao_parsers.parse_show_plot_page(self.cmd(cmd), cmd=cmd)

pytao.Tao.track_beam

track_beam(track_start=None, track_end=None, *, ix_branch='', ix_uni='', use_progress_bar=True, jupyter=None, restore_track_type=True)

Tracks the beam through the lattice by running:

set global track_type = beam

Parameters:

Name	Type	Description	Default
`track_start`	`str, int, or None`	Where to start tracking. If None (the default), uses the current tracking settings.	`None`
`track_end`	`str, int, or None`	Where to stop tracking. If None (the default), uses the current tracking settings.	`None`
`ix_branch`	`str`	Branch index, by default ""	`''`
`ix_uni`	`str`	Universe index, by default ""	`''`
`use_progress_bar`	`bool`	Whether to show a progress bar, by default True	`True`
`jupyter`	`bool \| None`	Whether running in Jupyter environment. If None (default), auto-detects the presence of Jupyter.	`None`
`restore_track_type`	`bool`	Restore the current track type after tracking the beam.	`True`

Returns:

Type	Description
`list of str`	Output from Tao.

Source code in pytao/tao.py

def track_beam(
    self,
    track_start: str | int | None = None,
    track_end: str | int | None = None,
    *,
    ix_branch: str = "",
    ix_uni: str = "",
    use_progress_bar: bool = True,
    jupyter: bool | None = None,
    restore_track_type: bool = True,
) -> list[str]:
    """
    Tracks the beam through the lattice by running:

    ```
    set global track_type = beam
    ```

    Parameters
    ----------
    track_start : str, int, or None, optional
        Where to start tracking.  If None (the default), uses the current
        tracking settings.
    track_end : str, int, or None, optional
        Where to stop tracking.  If None (the default), uses the current
        tracking settings.
    ix_branch : str, optional
        Branch index, by default ""
    ix_uni : str, optional
        Universe index, by default ""
    use_progress_bar : bool, optional
        Whether to show a progress bar, by default True
    jupyter : bool | None, optional
        Whether running in Jupyter environment. If None (default), auto-detects
        the presence of Jupyter.
    restore_track_type : bool, optional
        Restore the current track type after tracking the beam.

    Returns
    -------
    list of str
        Output from Tao.
    """
    glob = typing.cast(dict[str, Any], self.tao_global())

    prev_track_type = glob["track_type"]

    if track_start is not None:
        self.cmd(f"set beam_init track_start = {track_start}")

    if track_end is not None:
        self.cmd(f"set beam_init track_end = {track_end}")

    lat_calc_on = glob["lattice_calc_on"]

    set_beam_command = "set global track_type = beam"
    restore_beam_command = f"set global track_type = {prev_track_type.lower()}"

    commands = [set_beam_command]

    if not lat_calc_on:
        # Turn on lattice calculations for long enough to track the beam:
        commands.append("set global lattice_calc_on = T")
        # Toggle it off after finishing:
        commands.append("set global lattice_calc_on = F")

    if restore_track_type and set_beam_command != restore_beam_command:
        commands.append(restore_beam_command)

    with pbar.track_beam_wrapper(
        tao=self,
        ix_uni=ix_uni,
        ix_branch=ix_branch,
        use_progress_bar=use_progress_bar,
        jupyter=jupyter,
    ):
        return self.cmd("; ".join(commands))

pytao.Tao.unique_ele_ids

unique_ele_ids(*selectors)

Retrieve unique element IDs based on universe/branch-selectors and/or specific IDs.

If no selectors are specified, returns all unique element IDs from the superuniverse.

Parameters:

Name	Type	Description	Default
`*selectors`	`str`	List of universes, branches, or specific element IDs: - Full superuniverse: `None` or empty list - Specific universes: ["1", ...] - Universe-branch pair: ["1@2", ...] - Specific element IDs: ["1@2>>10", ...]	`()`

Returns:

Type	Description
`list of str`	A sorted list of resolved element IDs based on the provided selectors.

Notes

The accepted syntax includes: - {UNIVERSE} → All branches in the universe. - {UNIVERSE}@{BRANCH} → All elements in the branch. - {UNIVERSE}@{BRANCH}>>{ELEMENT} → A specific element ID.

Source code in pytao/tao.py

def unique_ele_ids(self, *selectors: str):
    """
    Retrieve unique element IDs based on universe/branch-selectors and/or specific IDs.

    If no selectors are specified, returns all unique element IDs from the superuniverse.

    Parameters
    ----------
    *selectors : str
        List of universes, branches, or specific element IDs:
        - Full superuniverse: `None` or empty list
        - Specific universes: ["1", ...]
        - Universe-branch pair: ["1@2", ...]
        - Specific element IDs: ["1@2>>10", ...]

    Returns
    -------
    list of str
        A sorted list of resolved element IDs based on the provided selectors.

    Notes
    -----
    The accepted syntax includes:
    - `{UNIVERSE}` → All branches in the universe.
    - `{UNIVERSE}@{BRANCH}` → All elements in the branch.
    - `{UNIVERSE}@{BRANCH}>>{ELEMENT}` → A specific element ID.
    """
    if not selectors:
        return self.unique_ele_ids_from_superuniverse()

    ele_ids = []

    for sel in selectors:
        if ">>" in sel:
            # Specific element ID (e.g., "1@2>>10")
            ele_ids.append(sel)
        elif "@" in sel:
            # Universe@Branch selector (e.g., "1@2")
            ix_uni, ix_branch = sel.split("@", 1)
            ele_ids.extend(
                self.unique_ele_ids_from_branch(ix_uni=ix_uni, ix_branch=ix_branch)
            )
        else:
            # Universe selector (e.g., "1")
            ele_ids.extend(self.unique_ele_ids_from_universe(ix_uni=sel))

    def ele_sort(ele: str):
        try:
            uni_branch, ix_ele = ele.split(">>")
            ix_uni, ix_branch = uni_branch.split("@")
        except Exception:
            raise ValueError(f"Malformed element ID: {ele}")
        return int(ix_uni), int(ix_branch), int(ix_ele)

    return sorted(ele_ids, key=ele_sort)

pytao.Tao.unique_ele_ids_from_branch

unique_ele_ids_from_branch(ix_uni, ix_branch)

Retrieve unique element IDs from a specific universe and branch.

Parameters:

Name	Type	Description	Default
`ix_uni`	`str or int`	The universe index (ID) from which the branch originates.	required
`ix_branch`	`str or int`	The branch index (ID) to retrieve element IDs from.	required

Returns:

Type	Description
`list of str`	A list of element IDs in the format "{ix_uni}@{ix_branch}>>{ele_id}".

Source code in pytao/tao.py

def unique_ele_ids_from_branch(
    self,
    ix_uni: str | int,
    ix_branch: str | int,
) -> list[str]:
    """
    Retrieve unique element IDs from a specific universe and branch.

    Parameters
    ----------
    ix_uni : str or int
        The universe index (ID) from which the branch originates.
    ix_branch : str or int
        The branch index (ID) to retrieve element IDs from.

    Returns
    -------
    list of str
        A list of element IDs in the format "{ix_uni}@{ix_branch}>>{ele_id}".
    """
    return [
        f"{ix_uni}@{ix_branch}>>{ele_id}"
        for ele_id in self.lat_list(
            "*",
            "ele.ix_ele",
            flags="-no_slaves",
            ix_uni=str(ix_uni),
            ix_branch=str(ix_branch),
        )
    ]

pytao.Tao.unique_ele_ids_from_superuniverse

unique_ele_ids_from_superuniverse()

Retrieve element IDs from all universes in the Tao superuniverse.

Returns:

Type	Description
`list of str`	A list of element IDs from all universes in the superuniverse.

Source code in pytao/tao.py

def unique_ele_ids_from_superuniverse(self) -> list[str]:
    """
    Retrieve element IDs from all universes in the Tao superuniverse.

    Returns
    -------
    list of str
        A list of element IDs from all universes in the superuniverse.
    """
    ele_ids = []
    for ix_uni in self.inum("ix_universe"):
        ele_ids.extend(self.unique_ele_ids_from_universe(ix_uni=ix_uni))
    return ele_ids

pytao.Tao.unique_ele_ids_from_universe

unique_ele_ids_from_universe(ix_uni)

Retrieve element IDs from all branches in a universe.

Parameters:

Name	Type	Description	Default
`ix_uni`	`str or int`	The universe index (ID) to retrieve element IDs from.	required

Returns:

Type	Description
`list of str`	A list of element IDs from all branches in the given universe.

Source code in pytao/tao.py

def unique_ele_ids_from_universe(self, ix_uni: str | int) -> list[str]:
    """
    Retrieve element IDs from all branches in a universe.

    Parameters
    ----------
    ix_uni : str or int
        The universe index (ID) to retrieve element IDs from.

    Returns
    -------
    list of str
        A list of element IDs from all branches in the given universe.
    """
    ele_ids = []
    for ix_branch in self.inum(f"{ix_uni}^ix_branch"):
        ele_ids.extend(self.unique_ele_ids_from_branch(ix_uni=ix_uni, ix_branch=ix_branch))
    return ele_ids

pytao.Tao.update_plot_shapes

update_plot_shapes(ele_name=None, *, layout=False, floor=False, shape_index=None, shape=None, color=None, shape_size=None, type_label=None, shape_draw=None, multi_shape=None, line_width=None)

Update shape plotting settings for layouts/floor plans.

Must set either (or both of) layout / floor to True.
Only the specified parameters will be updated for each shape. That is, if you only specify color then the color of every matching shape will be updated and the other settings (such as line_width) will remain the same.

Parameters:

Name	Type	Description	Default
`ele_name`	`str`	Update the shape only for this element name. If `ele_name` and `shape_index` are unspecified, these settings apply to all shapes.	`None`
`shape_index`	`int`	The numerical index of the shape to change. If `ele_name` and `shape_index` are unspecified, these settings apply to all shapes.	`None`
`layout`	`bool`	Apply the settings to lattice layout shapes.	`False`
`floor`	`bool`	Apply the settings to floor plan shapes.	`False`
`shape`	`str`	The shape to use. Choose from one of the following: * "box" * "xbox" * "bow_tie" * "rbow_tie" * "circle" * "diamond" * "x", * "r_triangle" * "l_triangle" * "u_triangle" * "d_triangle"	`None`
`color`	`str`	Color for the shape. Choose from one of the following: * "Not_Set" * "White" * "Black" * "Red" * "Green" * "Blue" * "Cyan" * "Magenta" * "Yellow" * "Orange" * "Yellow_Green" * "Light_Green" * "Navy_Blue" * "Purple" * "Reddish_Purple" * "Dark_Grey" * "Light_Grey" * "Transparent"	`None`
`shape_size`	`float`	Shape size.	`None`
`type_label`	`"s", "name", or "none"`	Show this label for each shape. `None` indicates no shape.	`None`
`shape_draw`	`bool`	Draw the shape.	`None`
`multi_shape`	`bool`	If it can be part of a multi-shape.	`None`
`line_width`	`int`	Width of lines used to draw the shape.	`None`

Returns:

Type	Description
`list of ShapeListInfo`

Source code in pytao/tao.py

def update_plot_shapes(
    self,
    ele_name: str | None = None,
    *,
    layout: bool = False,
    floor: bool = False,
    shape_index: int | None = None,
    shape: str | None = None,
    color: str | None = None,
    shape_size: float | None = None,
    type_label: Literal["s", "name", "none"] | None = None,
    shape_draw: bool | None = None,
    multi_shape: bool | None = None,
    line_width: int | None = None,
) -> list[ShapeListInfo]:
    """
    Update shape plotting settings for layouts/floor plans.

    * Must set either (or both of) `layout` / `floor` to `True`.
    * Only the specified parameters will be updated for each shape. That is,
      if you only specify `color` then the color of every matching shape
      will be updated and the other settings (such as `line_width`) will
      remain the same.

    Parameters
    ----------
    ele_name : str, optional
        Update the shape only for this element name.
        If `ele_name` and `shape_index` are unspecified, these settings
        apply to all shapes.
    shape_index : int, optional
        The numerical index of the shape to change.
        If `ele_name` and `shape_index` are unspecified, these settings
        apply to all shapes.
    layout : bool, default=False
        Apply the settings to lattice layout shapes.
    floor : bool, default=False
        Apply the settings to floor plan shapes.
    shape : str, optional
        The shape to use. Choose from one of the following:
        * "box"
        * "xbox"
        * "bow_tie"
        * "rbow_tie"
        * "circle"
        * "diamond"
        * "x",
        * "r_triangle"
        * "l_triangle"
        * "u_triangle"
        * "d_triangle"
    color : str, optional
        Color for the shape. Choose from one of the following:
        * "Not_Set"
        * "White"
        * "Black"
        * "Red"
        * "Green"
        * "Blue"
        * "Cyan"
        * "Magenta"
        * "Yellow"
        * "Orange"
        * "Yellow_Green"
        * "Light_Green"
        * "Navy_Blue"
        * "Purple"
        * "Reddish_Purple"
        * "Dark_Grey"
        * "Light_Grey"
        * "Transparent"
    shape_size : float, optional
        Shape size.
    type_label : "s", "name", or "none", optional
        Show this label for each shape. `None` indicates no shape.
    shape_draw : bool, optional
        Draw the shape.
    multi_shape : bool, optional
        If it can be part of a multi-shape.
    line_width : int, optional
        Width of lines used to draw the shape.

    Returns
    -------
    list of ShapeListInfo
    """

    who_list = []
    if layout:
        who_list.append("lat_layout")
    if floor:
        who_list.append("floor_plan")
    if not who_list:
        raise ValueError("Must specify either `layout` or `floor` plots")

    res = []
    for who in who_list:
        shape_list_info = typing.cast(list["ShapeListInfo"], self.shape_list(who))
        res.extend(shape_list_info)
        for info in shape_list_info:
            should_set = any(
                (
                    (ele_name is None and shape_index is None),
                    (ele_name == info["ele_name"]),
                    (ele_name and info["ele_name"].startswith(ele_name)),
                    (shape_index == info["shape_index"]),
                )
            )
            if not should_set:
                continue

            if type_label is not None:
                info["type_label"] = type_label
            if shape is not None:
                info["shape"] = shape
            if color is not None:
                info["color"] = color
            if shape_size is not None:
                info["shape_size"] = shape_size
            if shape_draw is not None:
                info["shape_draw"] = shape_draw
            if multi_shape is not None:
                info["multi_shape"] = multi_shape
            if line_width is not None:
                info["line_width"] = line_width

            self.shape_set(who=who, **info)

    return res

pytao.Tao.version

version()

Get the date-coded version.

Source code in pytao/tao.py

def version(self) -> datetime.datetime | None:
    """Get the date-coded version."""
    cmd = "show version"
    return _pytao_parsers.parse_show_version(self.cmd(cmd), cmd=cmd)

Tao

pytao.Tao

Attributes

pytao.Tao.bokeh property

pytao.Tao.matplotlib property

pytao.Tao.plot_manager property

Functions

pytao.Tao.archive

pytao.Tao.bunch_data

pytao.Tao.cmds

pytao.Tao.ele

pytao.Tao.eles

pytao.Tao.from_lattice_contents classmethod

pytao.Tao.get_active_beam_track_element

pytao.Tao.get_config

pytao.Tao.init

pytao.Tao.particles

pytao.Tao.plot

pytao.Tao.plot_field

pytao.Tao.plot_page

pytao.Tao.track_beam

pytao.Tao.unique_ele_ids

pytao.Tao.unique_ele_ids_from_branch

pytao.Tao.unique_ele_ids_from_superuniverse

pytao.Tao.unique_ele_ids_from_universe

pytao.Tao.update_plot_shapes

pytao.Tao.version

pytao.Tao.bokeh `property`

pytao.Tao.matplotlib `property`

pytao.Tao.plot_manager `property`

pytao.Tao.from_lattice_contents `classmethod`