Skip to content

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, lattice_file2=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.

To disable plotting entirely, leave plot with its default and set noplot=True.

 '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
lattice_file2 str or Path

Secondary Bmad lattice file, parsed after lattice_file. Equivalent to Tao's comma-delimited form: -lattice_file file1,file2.

 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 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
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,
    lattice_file2: 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._temp_dir = None
    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,
        lattice_file2=lattice_file2,
        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.default_universe property writable 
default_universe

Get the index of Tao's default universe (s%global%default_universe).

Graphs and curves with ix_universe = -1 refer to this universe.

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.

pytao.Tao.temporary_dir property 
temporary_dir

The temporary directory used by this Tao instance.

This is currently only used for particle files that need to exist throughout the Tao session for when beam tracking reinitializes.

Returns:

Type Description
Path

Methods:

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 
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
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 
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
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 
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
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=None, ix_branch='*', *, which='model', defaults=True, warn=True, ac_kicker=FillDefault('ac_kicker'), attrs=FillDefault('attrs'), bunch_params=FillDefault('bunch_params'), cartesian_map=FillDefault('cartesian_map'), cartesian_map_terms=FillDefault('cartesian_map_terms'), chamber_walls=FillDefault('chamber_walls'), comb=FillDefault('comb'), control_vars=FillDefault('control_vars'), cylindrical_map=FillDefault('cylindrical_map'), cylindrical_map_terms=FillDefault('cylindrical_map_terms'), elec_multipoles=FillDefault('elec_multipoles'), floor=FillDefault('floor'), gen_gradients=FillDefault('gen_gradients'), gen_gradient_curves=FillDefault('gen_gradient_curves'), grid_field=FillDefault('grid_field'), grid_field_points=FillDefault('grid_field_points'), lord_slave=FillDefault('lord_slave'), mat6=FillDefault('mat6'), methods=FillDefault('methods'), multipoles=FillDefault('multipoles'), orbit=FillDefault('orbit'), photon=FillDefault('photon'), spin_taylor=FillDefault('spin_taylor'), taylor=FillDefault('taylor'), 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.ele("Q1")

Do not warn if Q1 matches more than one element:

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

Get an Element but skip orbit calculations:

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

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

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

Get a minimal Element (disable everything explicit):

>>> ele = tao.ele("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. A universe/branch qualification in ele_id (e.g. "1@0>>Q1") takes precedence over ix_uni/ix_branch.

 required
ix_uni str, int, or None

Universe to use when ele_id is unqualified. Defaults to Tao's default universe (s%global%default_universe); "" and -1 mean the same.

 None
ix_branch str or int

Branch to use when ele_id is unqualified, by default "*" (all branches).

 '*'
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
ac_kicker bool

Fill AC kicker settings.

 FillDefault('ac_kicker')
attrs bool

Fill general attributes.

 FillDefault('attrs')
bunch_params bool

Fill bunch parameters.

 FillDefault('bunch_params')
cartesian_map bool

Fill cartesian map data.

 FillDefault('cartesian_map')
cartesian_map_terms bool

Fill cartesian map per-term data.

 False
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')
cylindrical_map bool

Fill cylindrical map data.

 FillDefault('cylindrical_map')
cylindrical_map_terms bool

Fill cylindrical map per-term data.

 False
elec_multipoles bool

Fill electric multipole data.

 FillDefault('elec_multipoles')
floor bool

Fill floor data.

 FillDefault('floor')
gen_gradients bool

Fill generalized gradient map data.

 FillDefault('gen_gradients')
gen_gradient_curves bool

Fill generalized gradient per-curve derivative tables.

 False
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')
methods bool

Fill tracking/calculation method settings.

 FillDefault('methods')
multipoles bool

Fill multipole data.

 FillDefault('multipoles')
orbit bool

Fill orbit data.

 FillDefault('orbit')
photon bool

Fill photon data.

 FillDefault('photon')
spin_taylor bool

Fill spin Taylor map data.

 FillDefault('spin_taylor')
taylor bool

Fill Taylor map data.

 FillDefault('taylor')
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 
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
def ele(
    self,
    ele_id: AnyElementID,
    ix_uni: str | int | None = None,
    ix_branch: str | int = "*",
    *,
    which: Which = "model",
    defaults: bool = True,
    warn: bool = True,
    # Individually fillable elements:
    ac_kicker: bool | FillDefault = FillDefault("ac_kicker"),  # noqa: B008
    attrs: bool | FillDefault = FillDefault("attrs"),  # noqa: B008
    bunch_params: bool | FillDefault = FillDefault("bunch_params"),  # noqa: B008
    cartesian_map: bool | FillDefault = FillDefault("cartesian_map"),  # noqa: B008
    cartesian_map_terms: bool | FillDefault = FillDefault("cartesian_map_terms"),  # noqa: B008
    chamber_walls: bool | FillDefault = FillDefault("chamber_walls"),  # noqa: B008
    comb: bool | FillDefault = FillDefault("comb"),  # noqa: B008
    control_vars: bool | FillDefault = FillDefault("control_vars"),  # noqa: B008
    cylindrical_map: bool | FillDefault = FillDefault("cylindrical_map"),  # noqa: B008
    cylindrical_map_terms: bool | FillDefault = FillDefault("cylindrical_map_terms"),  # noqa: B008
    elec_multipoles: bool | FillDefault = FillDefault("elec_multipoles"),  # noqa: B008
    floor: bool | FillDefault = FillDefault("floor"),  # noqa: B008
    gen_gradients: bool | FillDefault = FillDefault("gen_gradients"),  # noqa: B008
    gen_gradient_curves: bool | FillDefault = FillDefault("gen_gradient_curves"),  # noqa: B008
    grid_field: bool | FillDefault = FillDefault("grid_field"),  # noqa: B008
    grid_field_points: bool | FillDefault = FillDefault("grid_field_points"),  # noqa: B008
    lord_slave: bool | FillDefault = FillDefault("lord_slave"),  # noqa: B008
    mat6: bool | FillDefault = FillDefault("mat6"),  # noqa: B008
    methods: bool | FillDefault = FillDefault("methods"),  # noqa: B008
    multipoles: bool | FillDefault = FillDefault("multipoles"),  # noqa: B008
    orbit: bool | FillDefault = FillDefault("orbit"),  # noqa: B008
    photon: bool | FillDefault = FillDefault("photon"),  # noqa: B008
    spin_taylor: bool | FillDefault = FillDefault("spin_taylor"),  # noqa: B008
    taylor: bool | FillDefault = FillDefault("taylor"),  # noqa: B008
    twiss: bool | FillDefault = FillDefault("twiss"),  # noqa: B008
    wake: bool | FillDefault = FillDefault("wake"),  # noqa: B008
    wall3d: bool | FillDefault = FillDefault("wall3d"),  # noqa: B008
    wall3d_table: bool | FillDefault = FillDefault("wall3d_table"),  # noqa: B008
    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.ele("Q1")

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

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

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

    Get a minimal Element (disable everything explicit):
    >>> ele = tao.ele("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.
        A universe/branch qualification in `ele_id` (e.g. `"1@0>>Q1"`)
        takes precedence over `ix_uni`/`ix_branch`.
    ix_uni : str, int, or None, optional
        Universe to use when `ele_id` is unqualified.  Defaults to Tao's
        default universe (`s%global%default_universe`); `""` and
        `-1` mean the same.
    ix_branch : str or int, optional
        Branch to use when `ele_id` is unqualified, by default "*" (all
        branches).
    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`.
    ac_kicker : bool, optional
        Fill AC kicker settings.
    attrs : bool, optional
        Fill general attributes.
    bunch_params : bool, optional
        Fill bunch parameters.
    cartesian_map : bool, optional
        Fill cartesian map data.
    cartesian_map_terms : bool, default=False
        Fill cartesian map per-term data.
    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.
    cylindrical_map : bool, optional
        Fill cylindrical map data.
    cylindrical_map_terms : bool, default=False
        Fill cylindrical map per-term data.
    elec_multipoles : bool, optional
        Fill electric multipole data.
    floor : bool, optional
        Fill floor data.
    gen_gradients : bool, optional
        Fill generalized gradient map data.
    gen_gradient_curves : bool, default=False
        Fill generalized gradient per-curve derivative tables.
    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.
    methods : bool, optional
        Fill tracking/calculation method settings.
    multipoles : bool, optional
        Fill multipole data.
    orbit : bool, optional
        Fill orbit data.
    photon : bool, optional
        Fill photon data.
    spin_taylor : bool, optional
        Fill spin Taylor map data.
    taylor : bool, optional
        Fill Taylor map 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 = self._resolve_element_ids(
        str(ele_id),
        ix_uni=ix_uni,
        ix_branch=ix_branch,
        which=which,
    )

    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,
        ac_kicker=ac_kicker,
        attrs=attrs,
        bunch_params=bunch_params,
        cartesian_map=cartesian_map,
        cartesian_map_terms=cartesian_map_terms,
        chamber_walls=chamber_walls,
        comb=comb,
        control_vars=control_vars,
        cylindrical_map=cylindrical_map,
        cylindrical_map_terms=cylindrical_map_terms,
        elec_multipoles=elec_multipoles,
        floor=floor,
        gen_gradients=gen_gradients,
        gen_gradient_curves=gen_gradient_curves,
        grid_field=grid_field,
        grid_field_points=grid_field_points,
        lord_slave=lord_slave,
        mat6=mat6,
        methods=methods,
        multipoles=multipoles,
        orbit=orbit,
        photon=photon,
        spin_taylor=spin_taylor,
        taylor=taylor,
        twiss=twiss,
        wake=wake,
        wall3d=wall3d,
        wall3d_table=wall3d_table,
        comb_data=comb_data,
    )
pytao.Tao.ele_ids 
ele_ids(*selectors: str, no_slaves: bool = False, track_only: bool = False, sort_by: Literal['ix_ele'] | None = 'ix_ele', as_string: Literal[True] = True) -> list[str]

ele_ids(*selectors: str, no_slaves: bool = False, track_only: bool = False, sort_by: Literal['ix_ele'] | None = 'ix_ele', as_string: Literal[False]) -> list[ElementID]

ele_ids(*selectors, no_slaves=False, track_only=False, sort_by='ix_ele', as_string=True)

Retrieve unique element IDs matching Tao element locators.

If no locators are specified, returns all unique element IDs from all universes (the superuniverse).

Examples of selectors:

  • "Q1", "Q*", "quad::*" - by name, wildcard, or key. With no branch given, all branches are searched.
  • "5", "3:10" - by element index or index range. By default, branch 0 when no branch is given.
  • "XLINE>>*", "1@0>>Q*" - explicit branch (by index or name) and/or universe.
  • With no universe prefix, the default universe is used. Prefixes include:
    • N@ universe by index N
    • -1@ the default universe (see Tao.default_universe)
    • *@ all universes
    • [2:4,7]@ universe ranges/lists

A non-matching locator contributes no IDs (it does not raise).

Parameters:

Name Type Description Default
*selectors str

Tao element locators, {uni@}{~}{branch>>}{key::}ele_id (see also ElementID).

 ()
no_slaves bool

If set, multipass_slave and super_slave elements will not be included. Defaults to False. (Note: Tao.unique_ele_ids defaults this to True.)

 False
track_only bool

Only include elements in the tracking part of the lattice, excluding lord elements.

 False
sort_by ('ix_ele', None)

Sort the result by (universe, branch, ele_id). Pass None to instead preserve Tao's natural ordering (s-position), deduplicating in first-seen order.

 "ix_ele"
as_string bool

Return element IDs as canonical strings. Set to False to get ElementID instances instead.

 True

Returns:

Type Description
list of str or list of ElementID

A list of unique, canonical element IDs of the form {ix_uni}@{ix_branch}>>{ix_ele} - as strings by default, or as ElementID instances when as_string=False. Ordered per sort_by.
Source code in pytao/tao.py 
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
def ele_ids(
    self,
    *selectors: str,
    no_slaves: bool = False,
    track_only: bool = False,
    sort_by: Literal["ix_ele"] | None = "ix_ele",
    as_string: bool = True,
) -> list[str] | list[ElementID]:
    """
    Retrieve unique element IDs matching Tao element locators.

    If no locators are specified, returns all unique element IDs from all
    universes (the superuniverse).

    Examples of selectors:

    - `"Q1"`, `"Q*"`, `"quad::*"` - by name, wildcard, or key.
      With no branch given, all branches are searched.
    - `"5"`, `"3:10"` - by element index or index range.
      By default, branch 0 when no branch is given.
    - `"XLINE>>*"`, `"1@0>>Q*"` - explicit branch (by index or name) and/or
      universe.
    - With no universe prefix, the default universe is used. Prefixes
      include:
        - `N@` universe by index N
        - `-1@` the default universe (see `Tao.default_universe`)
        - `*@` all universes
        - `[2:4,7]@` universe ranges/lists

    A non-matching locator contributes no IDs (it does not raise).

    Parameters
    ----------
    *selectors : str
        Tao element locators, `{uni@}{~}{branch>>}{key::}ele_id`
        (see also `ElementID`).
    no_slaves : bool, optional
        If set, multipass_slave and super_slave elements will not
        be included. Defaults to False.
        (Note: `Tao.unique_ele_ids` defaults this to True.)
    track_only : bool, default=False
        Only include elements in the tracking part of the lattice,
        excluding lord elements.
    sort_by : {"ix_ele", None}, default="ix_ele"
        Sort the result by `(universe, branch, ele_id)`.  Pass `None` to
        instead preserve Tao's natural ordering (s-position), deduplicating
        in first-seen order.
    as_string : bool, default=True
        Return element IDs as canonical strings.  Set to False to get
        `ElementID` instances instead.

    Returns
    -------
    list of str or list of ElementID
        A list of unique, canonical element IDs of the form
        `{ix_uni}@{ix_branch}>>{ix_ele}` - as strings by default, or as
        `ElementID` instances when `as_string=False`.  Ordered per
        `sort_by`.
    """

    def sort_key(id_: ElementID) -> tuple[int, int, int]:
        assert id_.universe is not None
        assert id_.branch is not None
        return int(id_.universe), int(id_.branch), int(id_.ele_id)

    if not selectors:
        resolved = [
            ElementID.from_tao(ele_id)
            for ele_id in self.ele_ids_from_superuniverse(
                no_slaves=no_slaves,
                track_only=track_only,
            )
        ]
    else:
        resolved = []
        for sel in selectors:
            uni_part, branch_part, elements, negated = split_locator(sel)
            locator = "".join(
                [
                    "~" if negated else "",
                    f"{branch_part}>>" if branch_part is not None else "",
                    elements,
                ]
            )
            for ix_uni in self._expand_universe_spec(uni_part):
                resolved.extend(
                    self._resolve_element_ids(
                        locator,
                        ix_uni=ix_uni,
                        ix_branch="",
                        no_slaves=no_slaves,
                        track_only=track_only,
                    )
                )

    unique = {sort_key(id_): id_ for id_ in resolved}
    if sort_by == "ix_ele":
        ids = [unique[key] for key in sorted(unique)]
    elif sort_by is None:
        ids = list(unique.values())
    else:
        raise ValueError(f"Invalid sort_by: {sort_by!r}; expected 'ix_ele' or None")

    if as_string:
        return [id_.tao_string for id_ in ids]
    return ids
pytao.Tao.ele_ids_from_branch 
ele_ids_from_branch(ix_uni, ix_branch, *, no_slaves=False, track_only=False)

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. "" and -1 refer to Tao's default universe.

 required
ix_branch str or int

The branch index (ID) to retrieve element IDs from.

 required
no_slaves bool

If set, multipass_slave and super_slave elements will not be included. Defaults to False. (Note: Tao.unique_ele_ids_from_branch defaults this to True.)

 False
track_only bool

Only include elements in the tracking part of the lattice, excluding lord elements.

 False

Returns:

Type Description
list of str

A list of element IDs in the format "{ix_uni}@{ix_branch}>>{ix_ele}".
Source code in pytao/tao.py 
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
def ele_ids_from_branch(
    self,
    ix_uni: str | int,
    ix_branch: str | int,
    *,
    no_slaves: bool = False,
    track_only: bool = False,
) -> 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.
        `""` and `-1` refer to Tao's default universe.
    ix_branch : str or int
        The branch index (ID) to retrieve element IDs from.
    no_slaves : bool, optional
        If set, multipass_slave and super_slave elements will not
        be included. Defaults to False.
        (Note: `Tao.unique_ele_ids_from_branch` defaults this to True.)
    track_only : bool, default=False
        Only include elements in the tracking part of the lattice,
        excluding lord elements.

    Returns
    -------
    list of str
        A list of element IDs in the format "{ix_uni}@{ix_branch}>>{ix_ele}".
    """
    ix_uni = self._resolve_ix_uni(ix_uni)
    flags = ["-array_out"]
    if no_slaves:
        flags.append("-no_slaves")
    if track_only:
        flags.append("-track_only")
    return [
        f"{ix_uni}@{ix_branch}>>{ele_id}"
        for ele_id in self.lat_list(
            "*",
            "ele.ix_ele",
            flags=" ".join(flags),
            ix_uni=str(ix_uni),
            ix_branch=str(ix_branch),
        )
    ]
pytao.Tao.ele_ids_from_superuniverse 
ele_ids_from_superuniverse(*, no_slaves=False, track_only=False)

Retrieve element IDs from all universes in the Tao superuniverse.

Parameters:

Name Type Description Default
no_slaves bool

If set, multipass_slave and super_slave elements will not be included. Defaults to False. (Note: Tao.unique_ele_ids_from_superuniverse defaults this to True.)

 False
track_only bool

Only include elements in the tracking part of the lattice, excluding lord elements.

 False

Returns:

Type Description
list of str

A list of element IDs from all universes in the superuniverse.
Source code in pytao/tao.py 
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
def ele_ids_from_superuniverse(
    self,
    *,
    no_slaves: bool = False,
    track_only: bool = False,
) -> list[str]:
    """
    Retrieve element IDs from all universes in the Tao superuniverse.

    Parameters
    ----------
    no_slaves : bool, optional
        If set, multipass_slave and super_slave elements will not
        be included. Defaults to False.
        (Note: `Tao.unique_ele_ids_from_superuniverse` defaults this to True.)
    track_only : bool, default=False
        Only include elements in the tracking part of the lattice,
        excluding lord elements.

    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.ele_ids_from_universe(
                ix_uni=ix_uni,
                no_slaves=no_slaves,
                track_only=track_only,
            )
        )
    return ele_ids
pytao.Tao.ele_ids_from_universe 
ele_ids_from_universe(ix_uni, *, no_slaves=False, track_only=False)

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. "" and -1 refer to Tao's default universe.

 required
no_slaves bool

If set, multipass_slave and super_slave elements will not be included. Defaults to False. (Note: Tao.unique_ele_ids_from_universe defaults this to True.)

 False
track_only bool

Only include elements in the tracking part of the lattice, excluding lord elements.

 False

Returns:

Type Description
list of str

A list of element IDs from all branches in the given universe.
Source code in pytao/tao.py 
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
def ele_ids_from_universe(
    self,
    ix_uni: str | int,
    *,
    no_slaves: bool = False,
    track_only: bool = False,
) -> 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.
        `""` and `-1` refer to Tao's default universe.
    no_slaves : bool, optional
        If set, multipass_slave and super_slave elements will not
        be included. Defaults to False.
        (Note: `Tao.unique_ele_ids_from_universe` defaults this to True.)
    track_only : bool, default=False
        Only include elements in the tracking part of the lattice,
        excluding lord elements.

    Returns
    -------
    list of str
        A list of element IDs from all branches in the given universe.
    """
    ix_uni = self._resolve_ix_uni(ix_uni)
    ele_ids = []
    for ix_branch in self.inum(f"{ix_uni}^ix_branch"):
        ele_ids.extend(
            self.ele_ids_from_branch(
                ix_uni=ix_uni,
                ix_branch=ix_branch,
                no_slaves=no_slaves,
                track_only=track_only,
            )
        )
    return ele_ids
pytao.Tao.eles 
eles(ele_id=None, ix_uni=None, ix_branch='*', *, which='model', no_slaves=False, track_only=False, defaults=True, ac_kicker=FillDefault('ac_kicker'), attrs=FillDefault('attrs'), bunch_params=FillDefault('bunch_params'), cartesian_map=FillDefault('cartesian_map'), cartesian_map_terms=FillDefault('cartesian_map_terms'), chamber_walls=FillDefault('chamber_walls'), comb=FillDefault('comb'), control_vars=FillDefault('control_vars'), cylindrical_map=FillDefault('cylindrical_map'), cylindrical_map_terms=FillDefault('cylindrical_map_terms'), elec_multipoles=FillDefault('elec_multipoles'), floor=FillDefault('floor'), gen_gradients=FillDefault('gen_gradients'), gen_gradient_curves=FillDefault('gen_gradient_curves'), grid_field=FillDefault('grid_field'), grid_field_points=FillDefault('grid_field_points'), lord_slave=FillDefault('lord_slave'), mat6=FillDefault('mat6'), methods=FillDefault('methods'), multipoles=FillDefault('multipoles'), orbit=FillDefault('orbit'), photon=FillDefault('photon'), spin_taylor=FillDefault('spin_taylor'), taylor=FillDefault('taylor'), 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) {'ac_kicker', 'attrs', 'bunch_params', 'cartesian_map', 'chamber_walls', 'control_vars', 'cylindrical_map', 'elec_multipoles', 'floor', 'gen_gradients', 'grid_field', 'lord_slave', 'mat6', 'methods', 'multipoles', 'orbit', 'photon', 'spin_taylor', 'taylor', '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. A universe/branch qualification in ele_id (e.g. "1@0>>Q1") takes precedence over ix_uni/ix_branch.

 None
ix_uni str, int, or None

Universe to use for unqualified element IDs. Defaults to Tao's default universe (s%global%default_universe); "" and -1 mean the same.

 None
ix_branch str or int

Branch to use for unqualified element IDs, by default "*" (all branches).

 '*'
which "base", "model", or "design"

Specifies which Tao lattice to use, by default "model".

 'model'
no_slaves bool

If set, multipass_slave and super_slave elements will not be included. Defaults to False.

 False
track_only bool

Only include elements in the tracking part of the lattice, excluding lord elements.

 False
defaults bool

Fill default items. Defaults are set by name in Element.DEFAULTS.

 True
ac_kicker bool

Fill AC kicker settings.

 FillDefault('ac_kicker')
attrs bool

Fill general attributes.

 FillDefault('attrs')
bunch_params bool

Fill bunch parameters.

 FillDefault('bunch_params')
cartesian_map bool

Fill cartesian map data.

 FillDefault('cartesian_map')
cartesian_map_terms bool

Fill cartesian map per-term data.

 False
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')
cylindrical_map bool

Fill cylindrical map data.

 FillDefault('cylindrical_map')
cylindrical_map_terms bool

Fill cylindrical map per-term data.

 False
elec_multipoles bool

Fill electric multipole data.

 FillDefault('elec_multipoles')
floor bool

Fill floor data.

 FillDefault('floor')
gen_gradients bool

Fill generalized gradient map data.

 FillDefault('gen_gradients')
gen_gradient_curves bool

Fill generalized gradient per-curve derivative tables.

 False
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')
methods bool

Fill tracking/calculation method settings.

 FillDefault('methods')
multipoles bool

Fill multipole data.

 FillDefault('multipoles')
orbit bool

Fill orbit data.

 FillDefault('orbit')
photon bool

Fill photon data.

 FillDefault('photon')
spin_taylor bool

Fill spin Taylor map data.

 FillDefault('spin_taylor')
taylor bool

Fill Taylor map data.

 FillDefault('taylor')
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 
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
def eles(
    self,
    ele_id: AnyElementID | Sequence[AnyElementID] | None = None,
    ix_uni: str | int | None = None,
    ix_branch: str | int = "*",
    *,
    which: Which = "model",
    no_slaves: bool = False,
    track_only: bool = False,
    defaults: bool = True,
    # Individually fillable elements:
    ac_kicker: bool | FillDefault = FillDefault("ac_kicker"),  # noqa: B008
    attrs: bool | FillDefault = FillDefault("attrs"),  # noqa: B008
    bunch_params: bool | FillDefault = FillDefault("bunch_params"),  # noqa: B008
    cartesian_map: bool | FillDefault = FillDefault("cartesian_map"),  # noqa: B008
    cartesian_map_terms: bool | FillDefault = FillDefault("cartesian_map_terms"),  # noqa: B008
    chamber_walls: bool | FillDefault = FillDefault("chamber_walls"),  # noqa: B008
    comb: bool | FillDefault = FillDefault("comb"),  # noqa: B008
    control_vars: bool | FillDefault = FillDefault("control_vars"),  # noqa: B008
    cylindrical_map: bool | FillDefault = FillDefault("cylindrical_map"),  # noqa: B008
    cylindrical_map_terms: bool | FillDefault = FillDefault("cylindrical_map_terms"),  # noqa: B008
    elec_multipoles: bool | FillDefault = FillDefault("elec_multipoles"),  # noqa: B008
    floor: bool | FillDefault = FillDefault("floor"),  # noqa: B008
    gen_gradients: bool | FillDefault = FillDefault("gen_gradients"),  # noqa: B008
    gen_gradient_curves: bool | FillDefault = FillDefault("gen_gradient_curves"),  # noqa: B008
    grid_field: bool | FillDefault = FillDefault("grid_field"),  # noqa: B008
    grid_field_points: bool | FillDefault = FillDefault("grid_field_points"),  # noqa: B008
    lord_slave: bool | FillDefault = FillDefault("lord_slave"),  # noqa: B008
    mat6: bool | FillDefault = FillDefault("mat6"),  # noqa: B008
    methods: bool | FillDefault = FillDefault("methods"),  # noqa: B008
    multipoles: bool | FillDefault = FillDefault("multipoles"),  # noqa: B008
    orbit: bool | FillDefault = FillDefault("orbit"),  # noqa: B008
    photon: bool | FillDefault = FillDefault("photon"),  # noqa: B008
    spin_taylor: bool | FillDefault = FillDefault("spin_taylor"),  # noqa: B008
    taylor: bool | FillDefault = FillDefault("taylor"),  # noqa: B008
    twiss: bool | FillDefault = FillDefault("twiss"),  # noqa: B008
    wake: bool | FillDefault = FillDefault("wake"),  # noqa: B008
    wall3d: bool | FillDefault = FillDefault("wall3d"),  # noqa: B008
    wall3d_table: bool | FillDefault = FillDefault("wall3d_table"),  # noqa: B008
    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)
    {'ac_kicker', 'attrs', 'bunch_params', 'cartesian_map',
    'chamber_walls', 'control_vars', 'cylindrical_map', 'elec_multipoles',
    'floor', 'gen_gradients', 'grid_field', 'lord_slave', 'mat6',
    'methods', 'multipoles', 'orbit', 'photon', 'spin_taylor', 'taylor',
    '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.
        A universe/branch qualification in `ele_id` (e.g. `"1@0>>Q1"`)
        takes precedence over `ix_uni`/`ix_branch`.
    ix_uni : str, int, or None, optional
        Universe to use for unqualified element IDs.  Defaults to Tao's
        default universe (`s%global%default_universe`); `""` and
        `-1` mean the same.
    ix_branch : str or int, optional
        Branch to use for unqualified element IDs, by default "*" (all
        branches).
    which : "base", "model", or "design", optional
        Specifies which Tao lattice to use, by default "model".
    no_slaves : bool, optional
        If set, multipass_slave and super_slave elements will not
        be included. Defaults to False.
    track_only : bool, default=False
        Only include elements in the tracking part of the lattice,
        excluding lord elements.
    defaults : bool, default=True
        Fill default items.  Defaults are set by name in `Element.DEFAULTS`.
    ac_kicker : bool, optional
        Fill AC kicker settings.
    attrs : bool, optional
        Fill general attributes.
    bunch_params : bool, optional
        Fill bunch parameters.
    cartesian_map : bool, optional
        Fill cartesian map data.
    cartesian_map_terms : bool, default=False
        Fill cartesian map per-term data.
    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.
    cylindrical_map : bool, optional
        Fill cylindrical map data.
    cylindrical_map_terms : bool, default=False
        Fill cylindrical map per-term data.
    elec_multipoles : bool, optional
        Fill electric multipole data.
    floor : bool, optional
        Fill floor data.
    gen_gradients : bool, optional
        Fill generalized gradient map data.
    gen_gradient_curves : bool, default=False
        Fill generalized gradient per-curve derivative tables.
    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.
    methods : bool, optional
        Fill tracking/calculation method settings.
    multipoles : bool, optional
        Fill multipole data.
    orbit : bool, optional
        Fill orbit data.
    photon : bool, optional
        Fill photon data.
    spin_taylor : bool, optional
        Fill spin Taylor map data.
    taylor : bool, optional
        Fill Taylor map 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 ele_id is None or (not isinstance(ele_id, int) and not ele_id):
        ids = self.ele_ids_from_superuniverse(
            no_slaves=no_slaves,
            track_only=track_only,
        )
    else:
        ids = []
        if isinstance(ele_id, (str, int, ElementID)):
            ele_id = [ele_id]

        for id1 in ele_id:
            ids.extend(
                self._resolve_element_ids(
                    str(id1),
                    ix_uni=ix_uni,
                    ix_branch=ix_branch,
                    which=which,
                    no_slaves=no_slaves,
                    track_only=track_only,
                )
            )

    return [
        Element.from_tao(
            self,
            id_,
            defaults=defaults,
            ac_kicker=ac_kicker,
            attrs=attrs,
            bunch_params=bunch_params,
            cartesian_map=cartesian_map,
            cartesian_map_terms=cartesian_map_terms,
            chamber_walls=chamber_walls,
            comb=comb,
            control_vars=control_vars,
            cylindrical_map=cylindrical_map,
            cylindrical_map_terms=cylindrical_map_terms,
            elec_multipoles=elec_multipoles,
            floor=floor,
            gen_gradients=gen_gradients,
            gen_gradient_curves=gen_gradient_curves,
            grid_field=grid_field,
            grid_field_points=grid_field_points,
            lord_slave=lord_slave,
            mat6=mat6,
            methods=methods,
            multipoles=multipoles,
            orbit=orbit,
            photon=photon,
            spin_taylor=spin_taylor,
            taylor=taylor,
            twiss=twiss,
            wake=wake,
            wall3d=wall3d,
            wall3d_table=wall3d_table,
            comb_data=comb_data,
        )
        for id_ in ids
    ]
pytao.Tao.from_contents classmethod 
from_contents(lattice_contents='', init_file_contents='', plot_file_contents='', beam_file_contents='', beam_init_position_file_contents='', building_wall_file_contents='', data_file_contents='', hook_init_file_contents='', startup_file_contents='', var_file_contents='', **kwargs)

Initialize the Tao instance using its Bmad-format lattice contents.

Optionally, the contents of any of Tao's other startup files may be specified. Each is written to a temporary file for the duration of initialization.

Parameters:

Name Type Description Default
lattice_contents str

The Bmad-format lattice file contents (i.e., not a filename).

 ''
init_file_contents str

The tao.init-format namelist file contents.

If lattice_contents is specified, this file will automatically have its design_lattice(1)%file modified to refer to lattice_contents on disk.

 ''
plot_file_contents str

The tao_plot.init-format namelist file contents.

 ''
beam_file_contents str

Contents of the file containing the tao_beam_init namelist.

 ''
beam_init_position_file_contents str

Contents of the file containing initial particle positions.

 ''
building_wall_file_contents str

Contents of the file defining the building tunnel wall.

 ''
data_file_contents str

Contents of the file defining data for plotting and optimization.

 ''
hook_init_file_contents str

Contents of the init file for hook routines.

 ''
startup_file_contents str

Contents of the file with commands to run after parsing the Tao init file.

 ''
var_file_contents str

Contents of the file defining variables for plotting and optimization.

 ''
**kwargs

See Tao for other initialization keyword arguments. The file keyword argument matching any specified *_contents argument - lattice_file for lattice_contents, data_file for data_file_contents, and so on - may not be passed.

 {}
Source code in pytao/tao.py 
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
@classmethod
def from_contents(
    cls,
    lattice_contents: str = "",
    init_file_contents: str = "",
    plot_file_contents: str = "",
    beam_file_contents: str = "",
    beam_init_position_file_contents: str = "",
    building_wall_file_contents: str = "",
    data_file_contents: str = "",
    hook_init_file_contents: str = "",
    startup_file_contents: str = "",
    var_file_contents: str = "",
    **kwargs,
):
    """
    Initialize the Tao instance using its Bmad-format lattice contents.

    Optionally, the contents of any of Tao's other startup files may be
    specified.  Each is written to a temporary file for the duration of
    initialization.

    Parameters
    ----------
    lattice_contents : str, optional
        The Bmad-format lattice file contents (i.e., not a filename).
    init_file_contents : str, optional
        The `tao.init`-format namelist file contents.

        If `lattice_contents` is specified, this file will automatically
        have its design_lattice(1)%file modified to refer to
        `lattice_contents` on disk.
    plot_file_contents : str, optional
        The `tao_plot.init`-format namelist file contents.
    beam_file_contents : str, optional
        Contents of the file containing the `tao_beam_init` namelist.
    beam_init_position_file_contents : str, optional
        Contents of the file containing initial particle positions.
    building_wall_file_contents : str, optional
        Contents of the file defining the building tunnel wall.
    data_file_contents : str, optional
        Contents of the file defining data for plotting and optimization.
    hook_init_file_contents : str, optional
        Contents of the init file for hook routines.
    startup_file_contents : str, optional
        Contents of the file with commands to run after parsing the Tao
        init file.
    var_file_contents : str, optional
        Contents of the file defining variables for plotting and
        optimization.
    **kwargs :
        See `Tao` for other initialization keyword arguments.  The file
        keyword argument matching any specified `*_contents` argument -
        `lattice_file` for `lattice_contents`, `data_file` for
        `data_file_contents`, and so on - may not be passed.
    """

    if "contents" in kwargs:
        # Back-compat for old `from_lattice_contents`
        if lattice_contents:
            raise ValueError(
                "`contents` is an alias for `lattice_contents`; do not pass both."
            )
        lattice_contents = kwargs.pop("contents")

    file_to_contents = {}
    for key, contents_key, contents in (
        ("lattice_file", "lattice_contents", lattice_contents),
        ("init_file", "init_file_contents", init_file_contents),
        ("plot_file", "plot_file_contents", plot_file_contents),
        ("beam_file", "beam_file_contents", beam_file_contents),
        (
            "beam_init_position_file",
            "beam_init_position_file_contents",
            beam_init_position_file_contents,
        ),
        ("building_wall_file", "building_wall_file_contents", building_wall_file_contents),
        ("data_file", "data_file_contents", data_file_contents),
        ("hook_init_file", "hook_init_file_contents", hook_init_file_contents),
        ("startup_file", "startup_file_contents", startup_file_contents),
        ("var_file", "var_file_contents", var_file_contents),
    ):
        if not contents:
            continue
        if key in kwargs:
            raise ValueError(f"'{key}' is not allowed when '{contents_key}' is specified")
        file_to_contents[key] = contents

    if not file_to_contents:
        raise ValueError("At least one 'contents' argument must be specified.")

    with TemporaryDirectory(prefix="pytao_from_contents") as tempdir:
        temppath = pathlib.Path(tempdir)

        def make_file(key: str, contents: str) -> pathlib.Path:
            (temppath / key).write_text(contents)
            return temppath / key

        lattice = file_to_contents.pop("lattice_file", "")
        if lattice:
            kwargs["lattice_file"] = make_file("lattice_file", lattice)

        init = file_to_contents.pop("init_file", "")
        if init:
            if "lattice_file" in kwargs:
                init = set_design_lattice(init, str(kwargs["lattice_file"]), index=1)
            kwargs["init_file"] = make_file("init_file", init)

        for key, file_contents in file_to_contents.items():
            kwargs[key] = make_file(key, file_contents)

        return cls(**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 
1277
1278
1279
1280
1281
1282
1283
1284
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 
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
def get_config(self, ix_uni: str | int = "", 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.get_initial_particles 
get_initial_particles(ix_uni=1, *, which='model', ix_bunch=1, verbose=False)

Get the initial particles for the given universe.

Parameters:

Name Type Description Default
ix_uni str or int

Defaults to the primary universe, universe 1.

 1
which "base", "model", or "design"

Specifies which Tao lattice to use, by default "model".

 'model'
ix_bunch int

The bunch index. Defaults to 1.

 1
verbose bool

Passed to command functions (e.g., bunch_params). Defaults to False.

 False

Returns:

Type Description
ParticleGroup or None

If particles are configured and saved at track_start (typically BEGINNING), then the generated ParticleGroup will be returned. Otherwise, None will be returned.
Source code in pytao/tao.py 
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
def get_initial_particles(
    self,
    ix_uni: str | int = 1,
    *,
    which: str = "model",
    ix_bunch: int = 1,
    verbose: bool = False,
) -> ParticleGroup | None:
    """
    Get the initial particles for the given universe.

    Parameters
    ----------
    ix_uni : str or int, optional
        Defaults to the primary universe, universe 1.
    which : "base", "model", or "design", optional
        Specifies which Tao lattice to use, by default "model".
    ix_bunch : int, optional
        The bunch index. Defaults to 1.
    verbose : bool, optional
        Passed to command functions (e.g., bunch_params).  Defaults to
        False.

    Returns
    -------
    ParticleGroup or None
        If particles are configured and saved at `track_start` (typically `BEGINNING`),
        then the generated `ParticleGroup` will be returned.
        Otherwise, `None` will be returned.
    """
    conf = self.get_config(ix_uni=str(ix_uni))
    track_start = conf.beam.track_start or "BEGINNING"
    track_start_ele_id = ElementID(universe=int(ix_uni or 1), ele_id=track_start)

    try:
        return self.particles(
            track_start_ele_id.tao_string,
            which=which,
            ix_bunch=ix_bunch,
            verbose=verbose,
        )
    except TaoCommandError as ex:
        if "BEAM NOT SAVED AT ELEMENT" in str(ex):
            return None
        raise
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, lattice_file2=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
lattice_file2 str or Path

Secondary Bmad lattice file, parsed after lattice_file. Equivalent to Tao's comma-delimited form: -lattice_file file1,file2.

 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 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
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,
    lattice_file2: 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
    lattice_file2 : str or pathlib.Path, default=None
        Secondary Bmad lattice file, parsed after `lattice_file`.
        Equivalent to Tao's comma-delimited form:
        ``-lattice_file file1,file2``.
    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,
        lattice_file2=lattice_file2,
        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)

    in_subprocess = is_in_subprocess()

    if in_subprocess:
        # The parent process checks the Tao version; we do not.
        pass
    elif not self._tao_version_checked:
        self._tao_version_checked = True
        self._check_tao_version()

    if not in_subprocess:
        configure_logging_from_env()

    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 
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
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
    """

    from beamphysics import 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, ix_uni=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"
ix_uni int

Plot data from this universe. Sets the graph-level ix_universe, which every curve inherits unless it has its own ix_universe.

 None

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 
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
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,
    ix_uni: 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.
    ix_uni : int, optional
        Plot data from this universe.  Sets the graph-level ``ix_universe``,
        which every curve inherits unless it has its own ``ix_universe``.

    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 ix_uni is not None:
        kwargs["ix_uni"] = ix_uni

    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_ele_methods 
plot_ele_methods(ele_id='*', *, columns=None, ix_uni='', ix_branch='*', which='model', include_zero_length=False, show_names=True, show_csr_ds_step=None, include_layout=True, backend=None, **kwargs)

Plot element method settings as categorical lanes along the beamline.

Each method (e.g., tracking_method) becomes a horizontal lane, with each element drawn as a block spanning its longitudinal extent, colored by the method value.

Parameters:

Name Type Description Default
ele_id str

Element match string, using the same syntax as Tao.eles (e.g., "*", "1:20", "quad::*"). Only tracking elements are considered; lord elements are excluded.

 "*"
columns sequence of str

Method columns to plot, in order. Defaults to all categorical columns with data for the selected elements: tracking_method, mat6_calc_method, spin_tracking_method, csr_method, space_charge_method, field_calc, and ptc_integration_type.

 None
ix_uni str

Universe index. Uses the current default universe by default (see also Tao.default_universe).

 ""
ix_branch str

Branch index. Defaults to branch 0.

 "0"
which "model", "base", or "design"
"model"
include_zero_length bool

Include zero-length elements, drawn as thin vertical lines.

 False
show_names bool

Label method transitions with the element names before and after the transition point.

 True
show_csr_ds_step bool

Add a subplot of csr_ds_step vs s. The default (None) shows it only when CSR is active for at least one selected element.

 None
include_layout bool

Include a lattice layout plot at the bottom.

 True
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 
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
def plot_ele_methods(
    self,
    ele_id: str = "*",
    *,
    columns: Sequence[str] | None = None,
    ix_uni: str = "",
    ix_branch: str = "*",
    which: Which = "model",
    include_zero_length: bool = False,
    show_names: bool = True,
    show_csr_ds_step: bool | None = None,
    include_layout: bool = True,
    backend: str | None = None,
    **kwargs,
):
    """
    Plot element method settings as categorical lanes along the beamline.

    Each method (e.g., `tracking_method`) becomes a horizontal lane, with
    each element drawn as a block spanning its longitudinal extent, colored
    by the method value.

    Parameters
    ----------
    ele_id : str, default="*"
        Element match string, using the same syntax as `Tao.eles`
        (e.g., `"*"`, `"1:20"`, `"quad::*"`).
        Only tracking elements are considered; lord elements are excluded.
    columns : sequence of str, optional
        Method columns to plot, in order.  Defaults to all categorical
        columns with data for the selected elements:
        `tracking_method`, `mat6_calc_method`, `spin_tracking_method`,
        `csr_method`, `space_charge_method`, `field_calc`, and
        `ptc_integration_type`.
    ix_uni : str, default=""
        Universe index.  Uses the current default universe by default
        (see also `Tao.default_universe`).
    ix_branch : str, default="0"
        Branch index.  Defaults to branch 0.
    which : "model", "base", or "design", default="model"
    include_zero_length : bool, default=False
        Include zero-length elements, drawn as thin vertical lines.
    show_names : bool, default=True
        Label method transitions with the element names before and after
        the transition point.
    show_csr_ds_step : bool, optional
        Add a subplot of `csr_ds_step` vs s.  The default (`None`) shows
        it only when CSR is active for at least one selected element.
    include_layout : bool, default=True
        Include a lattice layout plot at the bottom.
    backend : {"bokeh", "mpl"}, optional
        The backend to use.  Auto-detects Jupyter and availability of bokeh
        to select a backend.
    """
    from .plotting.ele_methods import ElementMethodsPlotData

    manager = self._get_user_specified_backend(backend)
    data = ElementMethodsPlotData.from_tao(
        self,
        ele_id,
        ix_uni=self._resolve_ix_uni(ix_uni),
        ix_branch=ix_branch,
        which=which,
        include_zero_length=include_zero_length,
    )
    self.last_plot = manager.plot_ele_methods(
        data,
        columns=columns,
        show_names=show_names,
        show_csr_ds_step=show_csr_ds_step,
        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 
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
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 
865
866
867
868
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.set_initial_particles 
set_initial_particles(particles, *, ix_uni=1, n_particle=None, write_to=None)

Use particles as the initial beam at track_start for the given universe.

Parameters:

Name Type Description Default
particles ParticleGroup, pathlib.Path, or str

The particle group data to set, either an existing ParticleGroup instance or an openPMD-beamphysics format particle group hdf5 filename. If passed a ParticleGroup instance, a temporary hdf5 file will be written (by default) to a temporary directory that will only live as long as the Tao session itself. This may be overridden with write_to.

 required
ix_uni str or int

Defaults to the primary universe, universe 1.

 1
n_particle int

Number of particles to use; must be <= len(particles). Defaults to None, which is len(particles).

 None
write_to str or None

The filename to write particle data to. This is how to opt-out of the temporary directory mechanism.

 None

Returns:

Type Description
ParticleGroup

Read back from the initial element.
Source code in pytao/tao.py 
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
def set_initial_particles(
    self,
    particles: ParticleGroup | pathlib.Path | str,
    *,
    ix_uni: str | int = 1,
    n_particle: int | None = None,
    write_to: pathlib.Path | str | None = None,
) -> ParticleGroup:
    """
    Use `particles` as the initial beam at `track_start` for the given universe.

    Parameters
    ----------
    particles : ParticleGroup, pathlib.Path, or str
        The particle group data to set, either an existing `ParticleGroup`
        instance or an openPMD-beamphysics format particle group hdf5
        filename.
        If passed a `ParticleGroup` instance, a temporary hdf5 file will be
        written (by default) to a temporary directory that will only live
        as long as the Tao session itself. This may be overridden with
        `write_to`.
    ix_uni : str or int, optional
        Defaults to the primary universe, universe 1.
    n_particle : int, optional
        Number of particles to use; must be `<= len(particles)`.
        Defaults to `None`, which is `len(particles)`.
    write_to : str or None, optional
        The filename to write particle data to. This is how to opt-out of
        the temporary directory mechanism.

    Returns
    -------
    ParticleGroup
        Read back from the initial element.
    """
    glob = self.tao_global()
    track_type = glob["track_type"]

    if track_type == "beam":
        # Ensure we can toggle back to 'beam' to reinit particles
        self.cmd("set global track_type = single")

    if isinstance(particles, (pathlib.Path, str)):
        from beamphysics import ParticleGroup

        full_path = pathlib.Path(particles)
        particles = ParticleGroup(h5=particles)
    else:
        write_to = write_to or self.temporary_dir / (
            "initial_particles.h5"
            if int(ix_uni) == 1
            else f"initial_particles_uni_{ix_uni}.h5"
        )
        full_path = pathlib.Path(write_to)

    if write_to is not None:
        particles.write(write_to)

    ix_uni = str(ix_uni or 1)
    conf = self.get_config(ix_uni=ix_uni)

    orig_track_end = conf.beam.track_end
    track_start = conf.beam.track_start or "BEGINNING"
    track_start_ele_id = ElementID(universe=int(ix_uni), ele_id=track_start)

    conf.beam.track_end = track_start
    conf.beam_init.bunch_charge = particles.charge
    conf.beam_init.n_particle = min((n_particle or len(particles), len(particles)))
    conf.beam_init.position_file = str(full_path)
    try:
        conf.set(self, only_changed=True)
        with _ensure_global_block(self, "lattice_calc_on", True):
            self.cmd("set global track_type = beam; set global track_type = single")
    finally:
        conf.beam.track_end = orig_track_end
        conf.set(self, only_changed=True, suppress_lattice_calc=False)
    return self.particles(track_start_ele_id.tao_string)
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 
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
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 = 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.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 
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
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(*, as_date=False)

Get the Bmad/Tao library version.

Parameters:

Name Type Description Default
as_date bool

Return the version as a datetime instance instead of a string.

 False
Source code in pytao/tao.py 
853
854
855
856
857
858
859
860
861
862
863
def version(self, *, as_date: bool = False) -> datetime.datetime | str | None:
    """
    Get the Bmad/Tao library version.

    Parameters
    ----------
    as_date : bool, optional
        Return the version as a datetime instance instead of a string.
    """
    cmd = "show version"
    return _pytao_parsers.parse_show_version(self.cmd(cmd), cmd=cmd, as_date=as_date)