TaoConfig

TaoConfig captures the complete state of a running Tao session: startup parameters, Bmad common settings, space charge settings, beam initialization, beam tracking parameters, global settings, and per-element overrides.

It can generate set commands (all or only changed), apply them back to a Tao instance, and write reproducible bash loader scripts for archiving.

pytao.model.TaoConfig

Bases: TaoSettableModel

Tao Configuration model which defines how to start Tao and configure it.

Attributes:

Name	Type	Description
startup	TaoStartup	The startup configuration for Tao.
com	BmadCom	Bmad common settings.
space_charge_com	SpaceChargeCom	The space charge common settings.
beam_init	BeamInit	Initial settings for the beam.
beam	Beam	The beam parameters and settings.
globals	TaoGlobal	Tao global settings.
settings_by_element	dict of {str: dict of {str: str}}	Specific settings for each element (or matching elements/ranges), defined as a dictionary where keys are element names and values are dictionary of settings keys to values.

Attributes

pytao.model.TaoConfig.set_commands property

set_commands

Get all Tao 'set' commands to apply this configuration.

Returns:

Type	Description
list of str

Functions

pytao.model.TaoConfig.from_tao classmethod

from_tao(tao, ix_uni='', ix_branch='', **kwargs)

Get a configuration object representing the state of Tao.

Parameters:

Name	Type	Description	Default
tao	Tao		required
ix_branch	str	Branch index, by default ""	''
ix_uni	str	Universe index, by default ""	''

Returns:

Type	Description
TaoConfig

Source code in pytao/model/config.py

@classmethod
@override
def from_tao(cls, tao: Tao, ix_uni: str = "", ix_branch: str = "", **kwargs) -> TaoConfig:
    """
    Get a configuration object representing the state of Tao.

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

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

    Returns
    -------
    TaoConfig
    """
    return cls(
        startup=tao.init_settings,
        com=BmadCom.from_tao(tao, **kwargs),
        space_charge_com=SpaceChargeCom.from_tao(tao, **kwargs),
        beam_init=BeamInit.from_tao(tao, ix_uni=ix_uni, ix_branch=ix_branch, **kwargs),
        beam=Beam.from_tao(tao, ix_uni=ix_uni, ix_branch=ix_branch, **kwargs),
        globals=TaoGlobal.from_tao(tao, **kwargs),
    )

pytao.model.TaoConfig.get_set_commands

get_set_commands(tao=None)

Generate a list of set commands to apply this configuration to tao.

Parameters:

Name	Type	Description	Default
tao	Tao or None	An instance of the Tao class. If provided, only differing configuration parameters will be included in the list of set commands. If None, all attributes to be set will be used.	None

Returns:

Name	Type	Description
cmds	list of str

Source code in pytao/model/config.py

@override
def get_set_commands(self, tao: Tao | None = None) -> list[str]:
    """
    Generate a list of set commands to apply this configuration to `tao`.

    Parameters
    ----------
    tao : Tao or None, optional
        An instance of the Tao class.
        If provided, only differing
        configuration parameters will be included in the list of set
        commands.
        If `None`, all attributes to be set will be used.

    Returns
    -------
    cmds : list of str
    """
    if tao is None:
        return self.set_commands

    return sum(
        (
            self.com.get_set_commands(tao=tao),
            self.space_charge_com.get_set_commands(tao=tao),
            self.beam_init.get_set_commands(tao=tao),
            self.beam.get_set_commands(tao=tao),
            self.globals.get_set_commands(tao=tao),
            # TODO by element if changed
            self.per_element_commands,
        ),
        [],
    )

pytao.model.TaoConfig.write_bash_loader_script

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

Write a loader script to launch Tao with these startup parameters.

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
tao	Tao or None	If passed in, the Tao lattice will also be exported relative to the directory with lat_name as the name.	None
lat_name	str or None	The lattice filename to write, if tao is specified. Defaults to "{prefix}.lat.bmad".	None

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/model/config.py

def write_bash_loader_script(
    self,
    directory: pathlib.Path | str,
    prefix: str = "run_tao",
    *,
    mkdir: bool = True,
    tao: Tao | None = None,
    lat_name: str | None = None,
    shebang: str = "/usr/bin/env bash",
    tao_binary: str = "tao",
) -> tuple[pathlib.Path, pathlib.Path]:
    """
    Write a loader script to launch Tao with these startup parameters.

    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.
    tao : Tao or None, optional
        If passed in, the Tao lattice will also be exported relative
        to the directory with `lat_name` as the name.
    lat_name : str or None, optional
        The lattice filename to write, if `tao` is specified.
        Defaults to ``"{prefix}.lat.bmad"``.

    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`).
    """
    directory = pathlib.Path(directory).expanduser().resolve()
    if mkdir:
        directory.mkdir(exist_ok=True, parents=True)
    sh_file = directory / f"{prefix}.sh"
    cmd_file = directory / f"{prefix}.cmd"

    set_commands = [
        *(["set global plot_on = F"] if self.globals.plot_on else []),
        *(["set global lattice_calc_on = F"] if self.globals.lattice_calc_on else []),
        *self.set_commands,
        *(["set global plot_on = T"] if self.globals.plot_on else []),
        *(["set global lattice_calc_on = T"] if self.globals.lattice_calc_on else []),
    ]
    cmd_file.write_text("\n".join(set_commands))

    if tao is None:
        # No Tao instance - reuse the existing lattice on disk
        startup = self.startup
    else:
        # Tao instance - write lattice to disk with 'write bmad'
        if lat_name is None:
            lat_name = f"{prefix}.lat.bmad"

        startup = copy.deepcopy(self.startup)
        startup.init_file = None
        startup.lattice_file = lat_name

        full_lat_path = directory / lat_name
        if mkdir:
            full_lat_path.parent.mkdir(exist_ok=True, parents=True)
        tao.cmd(f"write bmad '{full_lat_path}'")

    lines = [
        f"#!{shebang}",
        f'{tao_binary} {startup.tao_init} -command "call {cmd_file.name}" "$@"',
    ]

    sh_file.write_text("\n".join(lines))
    return sh_file, cmd_file

TaylorMap

pytao.model.TaylorMap

Bases: TaoModel

Functions

pytao.model.TaylorMap.from_tao classmethod

from_tao(tao, ele1_id, ele2_id, *, order=1)

Create a TaylorMap instance from Tao.

Parameters:

Name	Type	Description	Default
tao	Tao		required
ele1_id	str or int	First element ID.	required
ele2_id	str or int	Second element ID.	required
order	str or int	Talor map order.	= 1

Returns:

Type	Description
TaylorMap

Source code in pytao/model/config.py

@classmethod
@override
def from_tao(
    cls: type[Self],
    tao: Tao,
    ele1_id: str | int,
    ele2_id: str | int,
    *,
    order: str | int = 1,
) -> Self:
    """
    Create a TaylorMap instance from Tao.

    Parameters
    ----------
    tao : Tao
    ele1_id : str or int
        First element ID.
    ele2_id : str or int
        Second element ID.
    order : str or int, default = 1
        Talor map order.

    Returns
    -------
    TaylorMap
    """
    data = cast(
        dict[int, dict[tuple[int, ...], float]],
        tao.taylor_map(
            ele1_id=str(ele1_id),
            ele2_id=str(ele2_id),
            order=str(order),
            raises=True,
        ),
    )
    return cls(ele1=str(ele1_id), ele2=str(ele2_id), order=order, taylor_map=data)

Settings Sub-Models

These are the TaoSettableModel subclasses that TaoConfig aggregates. Each corresponds to a Tao settings group and supports from_tao(), set_commands, get_set_commands(tao=...), and set(tao).

BmadCom

pytao.model.BmadCom

Bases: TaoSettableModel

Structure which corresponds to Tao pipe bmad_com, for example.

Attributes:

Name	Type	Description
abs_tol_adaptive_tracking	float	Runge-Kutta tracking absolute tolerance.
abs_tol_tracking	float	Closed orbit absolute tolerance.
absolute_time_ref_shift	bool	Apply reference time shift when using absolute time tracking?
absolute_time_tracking	bool	Absolute or relative time tracking?
aperture_limit_on	bool	Use apertures in tracking?
auto_bookkeeper	bool	Deprecated and no longer used.
autoscale_amp_abs_tol	float	Autoscale absolute amplitude tolerance (eV).
autoscale_amp_rel_tol	float	Autoscale relative amplitude tolerance
autoscale_phase_tol	float	Autoscale phase tolerance.
conserve_taylor_maps	bool	Enable bookkeeper to set ele%taylor_map_includes_offsets = F?
convert_to_kinetic_momentum	bool	Cancel kicks due to finite vector potential when doing symplectic
tracking? Set to True to test symp_lie_bmad against runge_kutta.
csr_and_space_charge_on	bool	Space charge switch.
d_orb	sequence of floats	Orbit deltas for the mat6 via tracking calc.
debug	bool	Used for code debugging.
default_ds_step	float	Default integration step for eles without an explicit step calc.
default_integ_order	int	PTC integration order.
electric_dipole_moment	float	Particle's EDM. Call set_ptc to transfer value to PTC.
fatal_ds_adaptive_tracking	float	If actual step size is below this particle is lost.
init_ds_adaptive_tracking	float	Initial step size
lr_wakes_on	bool	Long range wakefields
max_aperture_limit	float	Max Aperture.
max_num_runge_kutta_step	int	Maximum number of RK steps before particle is considered lost.
min_ds_adaptive_tracking	float	Min step size to take.
normalize_twiss	bool	Normalize matrix when computing Twiss for off-energy ref?
radiation_damping_on	bool	Radiation damping toggle.
radiation_fluctuations_on	bool	Radiation fluctuations toggle.
radiation_zero_average	bool	Shift damping to be zero on the zero orbit to get rid of sawtooth?
rel_tol_adaptive_tracking	float	Runge-Kutta tracking relative tolerance.
rel_tol_tracking	float	Closed orbit relative tolerance.
rf_phase_below_transition_ref	bool	Autoscale uses below transition stable point for RFCavities?
runge_kutta_order	int	Runge Kutta order.
sad_amp_max	float	Used in sad_mult step length calc.
sad_eps_scale	float	Used in sad_mult step length calc.
sad_n_div_max	int	Used in sad_mult step length calc.
significant_length	float	meter
spin_n0_direction_user_set	bool	User sets direction of n0 for closed geometry branches?
spin_sokolov_ternov_flipping_on	bool	Spin flipping during synchrotron radiation emission?
spin_tracking_on	bool	spin tracking?
sr_wakes_on	bool	Short range wakefields?
synch_rad_scale	float	Synch radiation kick scale. 1 => normal, 0 => no kicks.
taylor_order	int	Taylor order to use. 0 -> default = ptc_private%taylor_order_saved.

SpaceChargeCom

pytao.model.SpaceChargeCom

Bases: TaoSettableModel

Structure which corresponds to Tao pipe space_charge_com, for example.

Attributes:

Name	Type	Description
abs_tol_tracking	float	Absolute tolerance for tracking.
beam_chamber_height	float	Used in shielding calculation.
cathode_strength_cutoff	float	Cutoff for the cathode field calc.
csr3d_mesh_size	sequence of integers	Gird size for CSR.
diagnostic_output_file	str	If non-blank write a diagnostic (EG wake) file
ds_track_step	float	CSR tracking step size
dt_track_step	float	Time Runge kutta initial step.
lsc_kick_transverse_dependence	bool
lsc_sigma_cutoff	float	Cutoff for the 1-dim longitudinal SC calc. If a bin sigma is < cutoff
* sigma_ave then ignore.
n_bin	int	Number of bins used
n_shield_images	int	Chamber wall shielding. 0 = no shielding.
particle_bin_span	int	Longitudinal particle length / dz_bin
particle_sigma_cutoff	float	3D SC calc cutoff for particles with (x,y,z) position far from the
center. Negative or zero means ignore.
rel_tol_tracking	float	Relative tolerance for tracking.
sc_min_in_bin	int	Minimum number of particles in a bin for sigmas to be valid.
space_charge_mesh_size	sequence of integers	Gird size for fft_3d space charge calc.

BeamInit

pytao.model.BeamInit

Bases: TaoSettableModel

Structure which corresponds to Tao pipe beam_init, for example.

Attributes:

Name	Type	Description
a_emit	float	a-mode emittance
a_norm_emit	float	a-mode normalized emittance (emit * beta * gamma)
b_emit	float	b-mode emittance
b_norm_emit	float	b-mode normalized emittance (emit * beta * gamma)
bunch_charge	float	charge (Coul) in a bunch.
center	sequence of floats	Bench phase space center offset relative to reference.
center_jitter	sequence of floats	Bunch center rms jitter
distribution_type	Sequence[str]	distribution type (in x-px, y-py, and z-pz planes) "ELLIPSE", "KV",
"GRID", "FILE", "RAN_GAUSS" or "" = "RAN_GAUSS"
dpz_dz	float	Correlation of Pz with long position.
dt_bunch	float	Time between bunches.
ellipse_1_n_ellipse	int or None
ellipse_1_part_per_ellipse	int or None
ellipse_1_sigma_cutoff	float or None
ellipse_2_n_ellipse	int or None
ellipse_2_part_per_ellipse	int or None
ellipse_2_sigma_cutoff	float or None
ellipse_3_n_ellipse	int or None
ellipse_3_part_per_ellipse	int or None
ellipse_3_sigma_cutoff	float or None
emit_jitter	sequence of floats	a and b bunch emittance rms jitter normalized to emittance
full_6d_coupling_calc	bool	Use V from 6x6 1-turn mat to match distribution? Else use 4x4 1-turn
mat used.
grid_1_n_px	int or None
grid_1_n_x	int or None
grid_1_px_max	float or None
grid_1_px_min	float or None
grid_1_x_max	float or None
grid_1_x_min	float or None
grid_2_n_px	int or None
grid_2_n_x	int or None
grid_2_px_max	float or None
grid_2_px_min	float or None
grid_2_x_max	float or None
grid_2_x_min	float or None
grid_3_n_px	int or None
grid_3_n_x	int or None
grid_3_px_max	float or None
grid_3_px_min	float or None
grid_3_x_max	float or None
grid_3_x_min	float or None
ix_turn	int	Turn index used to adjust particles time if needed.
kv_a	float
kv_n_i2	int
kv_part_per_phi	sequence of integers
n_bunch	int	Number of bunches.
n_particle	int	Number of particles per bunch.
position_file	str	File with particle positions.
random_engine	str	Or 'quasi'. Random number engine to use.
random_gauss_converter	str	Or 'quick' or 'exact'. Uniform to gauss conversion method.
random_sigma_cutoff	float	Cut-off in sigmas.
renorm_center	bool	Renormalize centroid?
renorm_sigma	bool	Renormalize sigma?
sig_pz	float	pz sigma
sig_pz_jitter	float	RMS pz spread jitter
sig_z	float	Z sigma in m.
sig_z_jitter	float	bunch length RMS jitter
species	str	"positron", etc. "" => use referece particle.
spin	sequence of floats	Spin (x, y, z)
t_offset	float	Time center offset
use_particle_start	bool	Use lat%particle_start instead of beam_init%center, %t_offset, and
%spin?
use_t_coords	bool	If true, the distributions will be taken as in t-coordinates
use_z_as_t	bool	Only used if use_t_coords = .true. If true, z describes the t
distribution If false, z describes the s distribution

Beam

pytao.model.Beam

Bases: TaoSettableModel

Structure which corresponds to Tao pipe beam, for example.

Attributes:

Name	Type	Description
always_reinit	bool
comb_ds_save	float	Master parameter for %bunch_params_comb(:)%ds_save
ds_save	float	Min distance between points.
dump_at	str
dump_file	str
saved_at	str
track_beam_in_universe	bool	Beam tracking enabled in this universe?
track_end	str
track_start	str	Tracking start element.

TaoGlobal

pytao.model.TaoGlobal

Bases: TaoSettableModel

Structure which corresponds to Tao pipe global, for example.

Attributes:

Name	Type	Description
beam_timer_on	bool	For timing the beam tracking calculation.
box_plots	bool	For debugging plot layout issues.
bunch_to_plot	int	Which bunch to plot
concatenate_maps	bool	False => tracking using DA.
de_lm_step_ratio	float	Scaling for step sizes between DE and LM optimizers.
de_var_to_population_factor	float	DE population = max(n_var*factor, 20)
debug_on	bool	For debugging.
delta_e_chrom	float	Delta E used from chrom calc.
derivative_recalc	bool	Recalc before each optimizer run?
derivative_uses_design	bool	Derivative calc uses design lattice instead of model?
disable_smooth_line_calc	bool	Global disable of the smooth line calculation.
dmerit_stop_value	float	Fractional Merit change below which an optimizer will stop.
draw_curve_off_scale_warn	bool	Display warning on graphs?
external_plotting	bool	Used with matplotlib and gui.
label_keys	bool	For lat_layout plots
label_lattice_elements	bool	For lat_layout plots
lattice_calc_on	bool	Turn on/off beam and single particle calculations.
lm_opt_deriv_reinit	float	Reinit derivative matrix cutoff
lmdif_eps	float	Tollerance for lmdif optimizer.
lmdif_negligible_merit	float
merit_stop_value	float	Merit value below which an optimizer will stop.
n_opti_cycles	int	Number of optimization cycles
n_opti_loops	int	Number of optimization loops
n_threads	int	Number of OpenMP threads for parallel calculations.
n_top10_merit	int	Number of top merit constraints to print.
only_limit_opt_vars	bool	Only apply limits to variables used in optimization.
opt_match_auto_recalc	bool	Set recalc = True for match elements before each cycle?
opt_with_base	bool	Use base data in optimization?
opt_with_ref	bool	Use reference data in optimization?
opti_write_var_file	bool	"run" command writes var_out_file
optimizer	str	optimizer to use.
optimizer_allow_user_abort	bool	See Tao manual for more details.
optimizer_var_limit_warn	bool	Warn when vars reach a limit with optimization.
phase_units	str	Phase units on output.
plot_on	bool	Do plotting?
print_command	str
random_engine	str	Non-beam random number engine
random_gauss_converter	str	Non-beam
random_seed	int	Use system clock by default
random_sigma_cutoff	float	Cut-off in sigmas.
rf_on	bool	RFcavities on or off? Does not affect lcavities.
srdt_gen_n_slices	int	Number times to slice elements for summation RDT calculation
srdt_sxt_n_slices	int	Number times to slice sextupoles for summation RDT calculation
srdt_use_cache	bool	Create cache for SRDT calculations. Can use lots of memory if
srdt_*_n_slices large.
stop_on_error	bool	For debugging: False prevents tao from exiting on an error.
svd_cutoff	float	SVD singular value cutoff.
svd_retreat_on_merit_increase	bool
symbol_import	bool	Import symbols from lattice file(s)? Internal stuff
track_type	str	or 'beam'
unstable_penalty	float	Used in unstable_ring datum merit calculation.
var_limits_on	bool	Respect the variable limits?
var_out_file	str
wait_for_cr_in_single_mode	bool	For use with a python GUI.