CLI

The ACC module is packaged with a CLI that can be used to run the functionality of the SIMPA library.

Getting help

To get a list of all available commands and their flags, execute the help command.

To get information about a specific command, append the command with the -h or --help flag.

To look for commands it is possible to append the help command with a search term such as help create. This will display all the commands that contain the word "create" with their descriptions and arguments.

Running a script

Scripts can be created for the SIMPA package using the commands below. These scripts can then be run with the call -f "**filename**" command, where **filename** is replaced by the filename of the script.

Saving the command history to a script

The CLI offers a utility to write the written commands in the interactive CLI to a script, this can be done with the write-script -f "**filename**" command where **filename** is replaced with the desired output filename.

Other functionalities

Arithmetic expressions

The CLI offers the functionality to solve arithmetic expressions, these expressions are defined using parentheses and can be used in command calls and variable assignments. For example:

a = (10*15)

b = (a+(13/2))

c = (sin(b))

d = some-command -s (a*c)

Arrays and hashmaps

The CLI also offers the ability to pass arrays and hashmaps as command parameters or to save them to variables. These constructs can be defined over multiple lines, though the entries for the hashmap {key:value} should be on one line. For example:

a = [1.2, 43, 26, 99.0]

b = [{"key": 12}, {"key2": 13.2}, {"key3": 60}]

Commands

Appending a command with the -h flag will print the description and parameters for the command.

Usage: active-sequence [OPTIONS]...

Prints the name of the active sequence.

 

Usage: add-arbitrary [OPTIONS]...

Puts an element with arbitrary shape at the end of the beam line at the specified longitudinal position. Unlike for the bending and straight elements the arbitrary element must accompanied by a path which describes the trajectory of the ideal particle. The element is oriented such that the local Z axis of the element points in the same direction as the last vector in the reference orbit calculated so far. The element is rotated around the Z axis such that the local Y axis of the element points to the direction of the --local-y-axis parameter. The last vector of the path determines the Z direction at the exit of the element.

• [-n, --name], String, required, The name of the arbitrary element. This can be chosen as the user wishes.
• [-s, --scaling], Double, Scaling factor, default is 1.0
• [-lp, --long-pos], Double, required, Longitudinal position of the first point in the reference orbit of the element.
• [-gn, --group-name], String, The name of the group which this element belongs to. This can be chosen as the user wishes. All elements in a group will be expanded into a single field map and can be scaled together later. Individual elements in a group, however can have different scaling factors. If not given the element name will be used as group name.
• [-etn, --element-type-name], String, Name of the element type. This name must correspond to the name of an existing source strength file. The source strength file is named according to the conventions. Example: MYBENDING-SOLUTION.txt
• [-vc, --vacuum-chamber], Map, A vacuum chamber of this element, if any. If not given the aperture of the element will be constructed using the the default profile of the sequence.
• [-p, --path], String, required, Path file name. It gives the reference orbit in the element. The path file contains 3 numbers in each row describing 3D points which give the reference orbit inside the element.
• [-y, --local-y-axis], Vector3D, The local Y direction at the entry of the element. If not given, by default it is the global Y axis. It must be perpendicular to the first vector of the path which is the local Z axis.

 

Usage: add-bending [OPTIONS]...

Puts a bending at the end of the beam line with the center at the given at the longitudinal position along the reference orbit. The bending will be placed such, that the Z axis of the local coordinate system at the center of the bending points in the direction of the beam propagation. The reference orbit inside the bending is calculated automatically.

• [-n, --name], String, required, The name of the arbitrary element. This can be chosen as the user wishes.
• [-s, --scaling], Double, Scaling factor, default is 1.0
• [-l, --length], double, required, Length of the element [m]. The bending radius is calculated as: r = length / deflection
• [-d, --deflection], double, required, Deflection angle of the bending.
• [-t, --tilt], Double, Tilt angle [radian] around the local +Z direction according to the right hand convention. The bending will be placed with this rotation applied. If rotation is also given, first the rotation is applied, then the tilt.
• [-lp, --long-pos], Double, required, Longitudinal position of the bending center [m].
• [-etn, --element-type-name], String, required, Name of the element type. This name must correspond to the name of an existing source strength file. The source strength file is named according to the conventions. Example: MYBENDING-SOLUTION.txt
• [-gn, --group-name], String, The name of the group which this bending belongs to. This can be chosen as the user wishes. All elements in a group will be expanded into a single field map and can be scaled together later. Individual elements in a group, however can have different scaling factors. If not given the element name will be used as group name.
• [-vc, --vacuum-chamber], Map, A vacuum chamber of this element, if any. If not given the aperture of the element will be constructed using the the default profile of the sequence.
• [-r, --rotation], Rotation, A rotation of the element applied before adding to the sequence. This is useful when a transformed version of a source strengths file is needed. A rotation object can be created with the 'create-rotation" command. You can assign it to a variable and use in the command option.
• [-bt, --bending-type], String, The type of the bending.There are two type of bendings: "S" for sector bending and "R" for rectangular bending. The default is "S"

 

Usage: add-bpm [OPTIONS]...

Add a beam position monitor to the sequence. Useful together with the 'orbit-at-bpms' command to output the orbit at the BPM positions.

• [-p, --plane], String, required, The plane of the monitor. Allowed values: "H","V", "HV" for horizontal,vertical or both.
• [-n, --name], String, required, Name of the BPM.
• [-lp, --longitudinal-position], Double, required, The longitudinal position of the pickup center from the start of the reference orbit [m].

 

Usage: add-marker [OPTIONS]...

Adds a marker to the sequence. It is useful to mark a specific position in the sequence.

• [-n, --name], String, required, Name of the marker.
• [-lp, --longitudinal-position], Double, required, The longitudinal position from the start of the reference orbit [m].

 

Usage: add-straight [OPTIONS]...

Adds a straight element at the end of the beam line at the specified longitudinal position. It is assumed that the Z axis of the local coordinate system of the element to be added points in the direction of the beam propagation.

• [-n, --name], String, required, The name of the element to be added.
• [-s, --scaling], Double, Scaling factor, default is 1.0
• [-t, --tilt], Double, Tilt angle [radian] around the local +Z direction according to the right hand convention. The element will be placed with this rotation applied. If a rotation is also given, first the rotation is applied, then the tilt.
• [-lp, --long-pos], Double, required, Longitudinal position of the center of the element.
• [-gn, --group-name], String, The name of the group which this bending belongs to. This can be chosen as the user wishes. All elements in a group will be expanded into a single field map and can be scaled together later. Individual elements in a group, however can have different scaling factors. If not given the element name will be used as group name.
• [-etn, --element-type-name], String, Name of the element type. This name must correspond to the name of an existing source strength file. The source strength file is named according to the conventions. Example: MYELEMENT-SOLUTION.txt
• [-vc, --vacuum-chamber], Map, A vacuum chamber of this element, if any. If not given the aperture of the element will be constructed using the the default profile of the sequence.
• [-r, --rotation], Rotation, A rotation to be applied before putting the element into the sequence. If the element is oriented according to the conventions, such the local Z axis coincides with the reference orbit and the local Y axis points up, this should be the identity rotation. Typically used for mis-alignment or put an element into the sequence which was created with a non-standard orientation, for example the CAD model the element is calculated from is given such that the local Z axis is not the same as the reference orbit inside the element.

 

Usage: beam-from-file [OPTIONS]...

Create a beam for tracking from a file. The file must contain 6D phase space coordinates in each line in the following format: x xp y yp z zp (positions in meters) If the file contains more columns, the extra columns will be ignored. A typical usage is to create a beam from a file produced during tracking of a bunch in a transfer line by a phase space observer.

• [-t, --type], String, The particle type one of these are defined: "proton", "antiproton", "electron", "positron".
• [-m, --momentum], Double, required, The nominal momentum of the beam. The z' coordinates read from the file will be added to to this such that, for any particle: p = p0 + z' * p0 where p0 is the nominal momentum in [GeV/c].
• [-lp, --longitudinal-position], Double, required, The longitudinal position of the beam center from the start of the reference orbit [m]. The z coordinates in [m] read from the file will be added to this.
• [-mass, --mass], Double, The mass of the particle, if no type is given. Otherwise ignored. [kg].
• [-c, --charge], Double, The charge of the particle, if no type is given. Otherwise ignored. [Coulomb].
• [-na, --name], String, required, The name of the beam. This will be used by the observers for the output file names.
• [-f, --file], String, required, A file containing the phase space coordinates. There must be at least 6 columns, even for a 4D or 5D beam. In case of 4D or 5D beams the remaining coordinates should be set to zeros.

 

Usage: beam-twiss [OPTIONS]...

It returns and prints Twiss parameters from a phase space coordinate file of a beam containing many particles by calculating the beam co-variance matrix. The emittances are RMS 1 sigma emittances.

• [-f, --file], String, required, A file containing the phase space coordinates. There must be at least 6 columns, even for a 4D or 5D beam. In case of 4D or 5D beams the remaining coordinates should be set to zeros.

 

Usage: bobyqa-matcher [OPTIONS]...

Creates a BOBYQA optimizer for multivariate matching which should be assigned to a variable a passed to the --matcher parameter of the 'match' command. This matcher is fast, but can stuck to local minimum of the objective function. The objective function is the sum of absolute values of the differences between the target values and the actual values during the optimization. For the specific parameters of the BOBYQA optimizer see: https://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/BOBYQAOptimizer.html

• [-ip, --interpolation-points], Integer, Number of interpolation points. The default value is 2*n+1, where n is the number of variables.
• [-ir, --initial-region], Double, Initial trust region. Default is 10. The bigger this value the more search space will be explored around the initial guess.
• [-sf, --stop-fitness], Double, Stop if objective function value is smaller than this value. Default is 1e-6
• [-mi, --max-iterations], Integer, Maximum number iterations, after that many iterations the optimization stops and returns the current best value. Default is 1000.
• [-t, --targets], MatchingTarget[], required, An array of matching targets. The array length must be bigger than 1. A matching target can be created with the 'matching-target' command and assigned to a variable. Then those variables can be assembled to an array and given to this command. Example: mt1 = matching-target ... mt2 = matching-target ... mt3 = matching-target ... matcher=bobyqa-matcher --targets [mt1,mt2,mt3, ...] ..
• [-v, --variables], MatchingVariable[], required, An array of matching variables. The array length must be bigger than 1. A matching variable can be created with the 'matching-variable' command and assigned to a variable. Then those variables can be assembled to an array and given to this command. Example: mv1 = matching-variable ... mv2 = matching-variable ... mv3 = matching-variable ... matcher=bobyqa-matcher --variables [mv1,mv2,mv3, ...] ..

 

Usage: calculate-chromaticity [OPTIONS]...

Calculates the H and V chromaticities from 2 phase-space coordinate files. The two phase space files should contain data in the same format which is produced by a phase space observer during tracking in a ring. They should correspond to two different tracking with two particles with some momentum deviation.

• [-f1, --file1], String, required, A file containing the phase space coordinates obtained from tracking a particle in a ring with momentum p0, which is usually the nominal momentum.
• [-f2, --file2], String, required, A file containing the phase space coordinates obtained from tracking a particle in a ring with momentum p1 = p0+ p0 * dp/p.
• [-t, --turns], Integer, required, Number of turns taken from the file. It must be a power of two. The default is 64.
• [-dpop, --dpop], double, required, Relative momentum deviation between the momentums of the particles which were used for tracking and produced the the files: dpop = (p1-p0)/p0.

 

Usage: calculate-tunes [OPTIONS]...

Calculates the H and V fractional tunes by the NAFF algorithm from phase space coordinates file(s). When the directory parameter is given, the tunes are calculated for all files in the directory. In this case the output file parameter must be also present. The output file will contain the tunes for each file in the directory. Note that the number of turns must be a power of two. A good choice is 64 or 128.

• [-f, --file], String, A file containing the phase space coordinates. It must have at least as many lines as the --turns parameter.
• [-t, --turns], Integer, Number of turns taken from the file. The default is 64.
• [-st, --starting-turn], Integer, Starting turn. The default is zero.
• [-d, --directory], String, Directory containing the files to be processed. If this parameter is given, the file parameter is ignored and all files will be processed in the directory. The result will be written into the output file given by the --output-file parameter.
• [-of, --output-file], String, Output file in which the tunes will be written to. If this parameter is given, the tunes are calculated for all files in the given directory.

 

Usage: check-field [OPTIONS]...

Compares the field of the generated solution file by the 'create-acc-element' command with a given reference file. The reference file name is derived from the element name contained in the configuration parameter. The reference file is usually an output from a EM field calculation software, like COMSOL, EM studio, etc. See also the 'write-surface-points' and 'create-tiling-config' and 'create-acc-element' commands. These are part of the same work-flow to create a point source file for an accelerator element.

• [-tc, --tiling-config], TilingConfig, required, Tiling configuration object created with the 'create-tiling-config' command. The tiling configuration object should be assigned to a variable and that variable should be given to this command parameter.

 

Usage: cmaes-matcher [OPTIONS]...

Creates a CMAES optimizer for multivariate matching which should be assigned to a variable a passed to the --matcher parameter of the 'match' command. Recommended for finding global optimum. Slow, but reliable. The objective function is the sum of absolute values of the differences between the target values and the actual values during the optimization. See: https://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/optim/nonlinear/scalar/noderiv/CMAESOptimizer.html

• [-t, --targets], MatchingTarget[], required, An array of matching targets. The array length must be bigger than 1. A matching target can be created with the 'matching-target' command and assigned to a variable. Then those variables can be assembled to an array and given to this command. Example: mt1 = matching-target ... mt2 = matching-target ... mt3 = matching-target ... matcher=cmaes-matcher --targets [mt1,mt2,mt3, ...] ..
• [-v, --variables], MatchingVariable[], required, An array of matching variables. The array length must be bigger than 1. A matching variable can be created with the 'matching-variable' command and assigned to a variable. Then those variables can be assembled to an array and given to this command. Example: mv1 = matching-variable ... mv2 = matching-variable ... mv3 = matching-variable ... matcher=cmaes-matcher --variables [mv1,mv2,mv3, ...] ..
• [-sf, --stop-fitness], Double, Stop if objective function value is smaller than this value. Default is 1e-6
• [-mi, --max-iterations], Integer, Maximum number of iterations. Default is 1000.
• [-ac, --active-cma], Boolean, If true, using an active CMA algorithm. Default is true.
• [-si, --sigmas], Double[], Input sigma values. They define the initial coordinate-wise standard deviations for sampling new search points around the initial guess. It is suggested to set them to the estimated distance from the initial to the desired optimum. Small values induce the search to be more local and very small values are more likely to find a local optimum close to the initial guess. Too small values might however lead to early termination.
• [-cfc, --check-feasible-count], Integer, Determines how many times a not feasible solution (due to the constraints) will be tried to make feasible. Default is 5.
• [-ps, --polulation-size], Integer, Population size. Increasing the population size improves global search properties at the expense of speed. Default is 4 + 3*ln(n), where n is the number of variables.

 

Usage: convert-trajectory [OPTIONS]...

Converts a global trajectory to the local frame defined by the reference orbit of the sequence. Either a particle name or a beam name must be specified, but not both.

• [-pn, --particle-name], String, The particle name is used to determine the file name according to the naming conventions which contains the trajectory data produced by a trajectory observer during single particle tracking.
• [-bn, --beam-name], String, The beam name is used to determine the file name according to the naming conventions which contains the trajectory data produced by a trajectory observer during beam tracking.
• [-dr, --disk-radius], double, required, Disk radius [m]. Should be big enough to cover the full aperture, but small enough to not intersect with the orbit twice. The global trajectory(s) pierce through many disks along the reference
• [-of, --output-file], String, required, The output file. The layout of the file columns: 1: Longitudinal position in the sequence [m] 2: Horizontal position in the local coordinate system [m]. 3: Horizontal angle in the local coordinate system. 4: Vertical position in the local coordinate system [m]. 5: Vertical angle in the local coordinate system.
• [-bw, --backward], Boolean, Must be set true if the trajectory belongs to a tracking backward, in -Z direction of the reference orbit.

 

Usage: create-acc-element [OPTIONS]...

Create an accelerator element, requires tiling config to be set using the 'create-tiling-config' command. There are several options related to the solver. There are two type of solvers: direct and iterative solvers with GMRES. For GMRES there are three pre-conditioner implemented: jacobi,slice,blockjacobi.

• [-tc, --tiling-config], TilingConfig, required, Tiling configuration created with create-tiling-config.
• [-re, --relative-error], Double, required, Allowed relative error. Default is 1e-6. If an iterative solver is selected with the '--solver' option, it will stop after the residual is below the given limit.
• [-s, --solver], String, Specify the solver. Allowed values:"direct","jacobi","slice","blockjacobi". Default: slice. Jacoby is not recommended, usually converges very slowly, it is kept because of its simplicity. For accelerator elements usually the slice pre-conditioner is the best choice. This splits the problem into slices along the longitudinal direction and solves each slice directly. An assembly of sub-solutions are used as pre-conditioner. The block Jacobi does something similar, but instead of slicing along the longitudinal direction, a set of overlapping patches are solved directly and used as pre-conditioner. This is useful outside of accelerator physics problems, where there is no longitudinal direction which can be used for slicing.
• [-bjar, --bj-aggregate-radius], Double, The block-Jacobi pre-conditioner constructs first a coarse grid, then creates aggregates of surface points around each coarse grid point. The degree of coarsening is determined by the aggregateRadius parameter. The distance between the coarse points are more than the coarsening radius. After coarsening, it creates local direct solvers belonging to patches around each coarse point. The number of fine points in a patch must be at least the number of fine grid points in the aggregate belonging to the same coarse point. Therefore the patchRadius must be at least as big as the aggregateRadius, but usually bigger, to have some overlap. This overlap is needed to discard the result at the border of the patch, since those points can be far from the solution, due to the finite extent of the patch. Only the local solution belonging to the aggregate is used for pre-conditioning.
• [-bjpr, --bj-patch-radius], Double, Patch radius [m] for the block-Jacobi pre-conditioner. Must be bigger than the aggregate radius.
• [-sw, --slice-width], Integer, Slice width in terms of number of profiles for the slice pre-conditioner, default is 1.
• [-bjpr, --slice-overlap], Integer, Slice overlap in terms of number of profiles for the slice pre-conditioner, default is 1.
• [-rst, --gmres-restart], Integer, Restart parameter for GMRES, default is 100. After the the given number of iterations the GMRES solver is restarted. Higher numbers gives usually faster convergence, but also higher memory consumption.
• [-d, --debug], Boolean, Outputs debug files for the block Jacobi and slice pre-conditioners These are: /tmp/coarseGrid.txt - The coordinates of the coarse grid points. /tmp/fineGrid.txt - The coordinates of the fine grid points. /tmp/aggregates.txt - The coordinates of the aggregates.

 

Usage: create-beam [OPTIONS]...

Create a beam for tracking in the selected sequence. The beam should be assigned to a variable and passes to the track command.

• [-t, --type], String, The particle type one of these are defined: "proton", "antiproton", "electron", "positron." If non of there pre-defined particles are tracked, the --momentum and --charge parameters must be specified and this parameter should not be given.
• [-m, --momentum], Double, required, The momentum of the beam [GeV/c].
• [-he, --h-emittane], Double, The horizontal 1 sigma emittance of the beam [m*rad]. If not given,taken from the Twiss parameter.
• [-ve, --v-emittane], Double, The vertical 1 sigma emittance of the beam [m*rad]. If not given, taken from the Twiss parameter
• [-lp, --longitudinal-position], Double, The longitudinal position compared to the start of the reference orbit [m].
• [-dp, --dpop], Double, Relative momentum deviation (1 sigma) from the reference momentum.
• [-mass, --mass], Double, The mass of the particle, if no particle type is given. Otherwise ignored. [kg].
• [-c, --charge], Double, The charge of the particle, taken into account only when no particle type is given. Otherwise ignored. [Coulomb].
• [-na, --name], String, required, The name of the beam. During the tracking various tracking observers write files based on the beam name.
• [-di, --distribution], String, required, The type of the distribution: 'gaussian' or 'ellipse'.
• [-n, --number-of-particles], Integer, required, The number of particles in the beam.
• [-twp, --twiss-parameters], TwissParameters, A TwissParameters object to be used at the given longitudinal position for transfer lines. For rings it is ignored and the calculated optics is used instead.

 

Usage: create-beam-region [OPTIONS]...

Creates a default vacuum chamber by extruding a profile along the design orbit and add all vacuum chambers specified in the sequence, if any. The command writes a cover with extension acoording to the naming convenvtions.The command also writes an STL file. It can be used for checking the beam region by displaying it in a 3D viewer, like Paraview. The command returns the name of the cover file.

• [-dp, --default-profile], Profile, required, A default profile. It is used everywhere along the design orbit to define the beam region unless a vacuum chamber is specifically given for one or more element(s) in the sequence. In that case the default profiles are replaced in the region of the the given vacuum chamber(s).
• [-d, --distance], double, required, The distance between the default profiles [m].
• [-br, --ball-radius], Double, If this parameter is given, the beam region is covered by balls with the given radius and a HCP cover file is created with the name of the active sequence and with the extension according to the nameing conventions. If not given, no HCP latticle cover file will be created. In that case a single row cover file can be created with the 'create-single-row-cover' command.
• [-ext, --extension], Double, In case of transfer lines, the beam region covered is extended some distance at the start of the sequence in the negative S direction and at the end of the sequence in the positive S direction to surely cover the fist and last step of the tracking. The extension parameter is ignored for rings. Unit is in [m]. Default value is 0.05 [m]

 

Usage: create-bending-path [OPTIONS]...

Create a path for a bending element using a deflection angle, bending radius and the number of segments in the path. The number of segments must be even. The path is used for tiling the surface surrounding the accelerator element. See also the related commands: 'create-tiling-config' and 'create-acc-element'

• [-da, --deflection-angle], Double, required, The deflection angle of the bending element[radians].
• [-r, --radius], Double, required, The bending radius of the element [m].
• [-ns, --number-of-segments], Integer, required, The number of segments in the path. Must be a positive even number. This number determines the longitudinal density of the surface points surrounding the beam region. This influences the accuracy of the reconstruction of the field of the element.
• [-el, --extention-length], Double, The output path consists of an arc and two straight sections at the ends. The length [m] of the straight extentions at both ends of the arc is determined by this value.
• [-n, --name], String, required, The name of the element. The output file name will be constructed from this using the file naming conventions. Such as: "elementname-PATH.txt"
• [-t, --translation], Vector3D, A translation to be applied after the rotation if any. The translation vector can be created by the 'create-vector3d' command and assigned to a variable. The variable then can be given to this command option.
• [-rot, --rotation], Rotation, A rotation to be applied, before the translation if any. The rotation can be created by the 'create-rotation' command and assigned to a variable. The variable then can be given to this command option.
• [-bt, --bending-type], String, required, The type of the bending. 'S' stands for sector bending and 'R' for rectangular bending. The default is 'S. For a rectangular bending the entry direction of the beam is the +Z axis. For sector bending the angle between the beam entry direction and the +Z axis is deflection/2.

 

Usage: create-checkpoint-file [OPTIONS]...

Creates a file based on the path file. It can be used for getting the field values from the EM field calculation software. Usually the path file is up-sampled to have a higher resolution. It maybe also shifted, for example for a quadrupole which have zero transverse field at the center. The path file can be also extended at both ends to see better the residual of the field. It is typically used after the 'create-acc-element' command to compare the field obtained from the solution file to the reference field values. The reference field is often obtained at a set of points from an EM field calculation software like COMSOL or OPERA, which needs a list of 3D points as an input and it outputs another file containing in each row the coordinates of the checkpoints and the values of the field components. This reference field file is taken by the 'check-field' command to calculate the error of the reconstructed field.

• [-tc, --tiling-config], TilingConfig, required, Tiling configuration created with 'create-tiling-config' command. This object contains most of the information needed by this command.
• [-tr, --translation], Vector3D, The translation to be applied to the path file, default is zero vector.
• [-e, --extention], Double, An extension to be added at both ends of the path, default is 0 [m].
• [-rss, --resampling-step-size], Double, required, Step size [m] for the up-sampling of the path.

 

Usage: create-ellipse-profile [OPTIONS]...

Creates an ellipse shaped profile used for constructing the beam region, or a vacuum chamber of one or more specific element. It is also used for creating the boundary surface around an accelerator element for determining the strength of point sources, see also the 'create-tiling-config' command. The profile is defined by the horizontal and vertical radius and the number of steps in the profile. The profile is sampled at the given number of steps and the points are connected by straight lines. The profile is closed, the last point is connected to the first one. The coordinate system of the profile is defined is 2D, it is in the X Y plane. These profiles are extruded along the reference orbit to create the beam region or a vacuum chamber for n element.

• [-xr, --x-radius], double, required, Horizontal radius of the ellipse [m].
• [-yr, --y-radius], double, required, Vertical radius of the ellipse [m].
• [-s, --steps], int, required, Number of steps in the profile. When the profile is used for constructing the boundary surface of an accelerator element, this number determines the density of the surface points at which the field of the point sources will be matched to the given input field. The higher the number the more accurate the field recosntruction will be.
• [-sa, --start-angle], Double, Starting angle of the first step. Between 0 and 2*Pi, zero by default. This parameter is used for avoid twisting between neighboring profiles when they are connected. If this parameter is zero, the first profile points starts at fi = -3*PI/4. This is because a rectangular profile starts at the left bottom corner. We need to align the ellipse profile to start at the same angle.

 

Usage: create-fieldmaps [OPTIONS]...

Executes the solid harmonic expansion using a cover file. The result is a field map. The field map can be used for tracking. The field map is written to binary file.

• [-cf, --cover-file], String, required, Cover file. The cover file contains the centers of the balls and the radius of the balls. The cover file can be created by the 'create-beam-region' or the 'create-single-row-cover' command.
• [-g, --group], String, The name of the group to be expanded. If null, all groups will be expanded into a single field map. The group names are given at the construction of the sequence. Usually a group consists of the elements connected to the same power supply and scaled together.
• [-obo, --one-by-one], Boolean, If true each group in the sequence will be expanded into separate field maps. In this case the group name should not be given.
• [-l, --lmax], int, required, L_max is the maximum degree of the solid harmonic expansion. The actual expansion degree is determined in a filtering phase to be below the error limit. This makes the field map smaller and faster to evaluate. The expansion has two passes. The first pass is done with a lower degree, which is given by the --lmax-pass1 parameter. Choosing that parameter properly saves time by avoiding unneded high degree expansion of all balls. In the second pass the lmax given here is used and a second filtering phase follows.
• [-lp1, --lmax-pass1], Integer, The expansion has two passes. The first pass is done with the degree given by this parameter. Choosing properly saves time at the creation of the field maps by avoiding unneded high degree expansion of all balls. Default is lmax/3.
• [-re, --relative-error], Double, Relative error limit for the expansion. Small spherical harmonic coefficients are dropped below that. Default is 1E-14
• [-st, --statistic], Boolean, Writes statistics about the distribution of maximum degrees of the balls in the map.

 

Usage: create-particle [OPTIONS]...

Create a particle for tracking. The particle should be assigned to a variable and passed to the 'track' command.

• [-t, --type], String, The particle type. The following types are defined: "proton", "antiproton", "electron", "positron". Ithis list likely to be extended in the future. If the particle type is given, the --mass and --charge parameters are ignored. If the particle you want to track is not in the list, you can specify the mass and charge using the --mass and --charge parameters.
• [-m, --momentum], Double, required, The momentum of the particle [GeV/c].
• [-dx, --x_position], Double, required, The horizontal position from the reference orbit [m].
• [-ax, --x_angle], Double, required, The horizontal angle compared to the reference orbit [rad].
• [-dy, --y_position], Double, required, The vertical position from the reference orbit [m].
• [-ay, --y_angle], Double, required, The vertical angle compared to the reference orbit [rad].
• [-lp, --longitudinal-position], Double, The longitudinal position compared to the start of the reference orbit [m].
• [-dp, --dpop], Double, Relative momentum deviation from the reference momentum: (p-p0)/p0
• [-mass, --mass], Double, The mass [kg] of the particle, should be given only if no particle type is given, otherwise ignored.
• [-c, --charge], Double, The charge of the particle [Coulomb], should be given only if no particle type is given, otherwise ignored.
• [-n, --name], String, The name of the particle. The name is used by the tracking observers to write trajectory of phase-space data files. If not given a default name is used, which is 'noname'

 

Usage: create-rect-profile [OPTIONS]...

Creates a rectangular shaped profile that can be saved and used to create the vacuum chamber around the beam region or individual vacuum chambers. It is also used for creating the boundary surface around an accelerator element for determining the strength of point sources, see also the 'create-tiling-config' command. The coordinate system of the profile is defined is 2D, it is in the X Y plane. These profiles are extruded along the reference orbit to create the beam region or a vacuum chamber for n element.

• [-xmin, --xmin], double, required, Minimum X coord. of the profile [m].
• [-xmax, --xmax], double, required, Maximum X coord. of the profile [m].
• [-ymin, --ymin], double, required, Minimum Y coord. of the profile.
• [-ymax, --ymax], double, required, Maximum Y coord. of the profile.
• [-xsteps, --x-steps], int, required, Number of steps in the X direction.
• [-ysteps, --y-steps], int, required, Number of steps in the Y direction.

 

Usage: create-rotation [OPTIONS]...

Creates a Rotation object using either four vectors or a vector and an angle. When 4 vectors are given, the rotation is constructed from the vectors such that the first and second vectors are rotated to the third and fourth vectors respectively. When a vector and an angle is given, the rotation is constructed such that the rotation is around the vector by the given angle. The vectors can be created by the 'create-vector3d' command and assigned to a variable. The variable then can be given to this command.

• [-v1], Vector3D, required, Vector1. Only this vector is used when a vector and an angle is given.
• [-v2], Vector3D, Vector2, used when 4 vector defines the rotation
• [-v3], Vector3D, Vector3, used when 4 vectors defines the rotation,
• [-v4], Vector3D, Vector4, used when 4 vectors defines the rotation,
• [-a, --angle], Double, Angle in radians counter-clockwise. Used only when a vector and this angle defines the rotation.

 

Usage: create-sequence [OPTIONS]...

Creates a sequence for an accelerator that can contain the accelerator elements. The sequence holds the reference orbit, the optics and the beam line elements. The sequence with the given name is automatically stored, no need to assign it to a variable. The sequence can be made active by the 'use-sequence' command. Elements can be added to the sequence by the following commands: 'add-arbitrary','add-bending','add-bpm','add-marker','add-staright'. After all elements has been added, the sequence should be closed by the 'end-sequence' command.

• [-n, --name], String, required, The name for the sequence. The sequence is stored with this name and can be made active by the 'use-sequence' command.
• [-oss, --orbit-step-size], Double, Orbit step size [m]. It determines the resolution of the optics calculation. Default is 0.01 m
• [-ci, --circular], Boolean, Whether the sequence is a circular machine or a transfer line. Circular by default, if not given.
• [-lfs, --local-frame-strategy], String, A strategy to construct the local coordinates. Allowed values: "PARALLEL_TRANSPORT" (default) or "MINIMIZE_TORSION". For a planar machine these are equivalent. For a non-planar machine the "MINIMIZE_TORSION" strategy tries to minimize the torsion of the local coordinate system. The "PARALLEL_TRANSPORT" strategy parallel transports the given Y vector along the reference orbit. See p. 9 and p. 10 of 'Parallel Transp ort Approach to Curve Framing' by Andrew J. Hanson and Hui Ma See: https://legacy.cs.indiana.edu/ftp/techreports/TR425.pdf The local frames along the reference orbit can be written to files by the 'end-sequence' command options and plotted or used otherwise.
• [-va, --vertical-axis], Vector3D, The preferred vertical direction for constructing the local coordinates (+Y by default) This option is usually used only when the a transfer line in a non-planar and the vertical direction is non-trivial. The vector can be created by the 'create-vector3d' command and assigned to a variable. The variable then can be given to this command option.

 

Usage: create-single-row-cover [OPTIONS]...

Creates a cover for the orbit and writes it to a cover file. A single row of overlapping spheres are placed along the reference orbit. An active sequence must be selected before this command is used. The spheres are placed such that they cover the entire volume of the beam region without gaps. The distances between the sphere centers are determined by the given aperture radius and the ball radius. This type of cover can be used for simple beam lines or rings with uniform circular cross section. For more complex shapes use the 'create-beam-region' command. The single row cover is slower to evaluate at tracking time than the lattice cover, but it is faster to create and the size of the cover file is smaller. The output file name returned is derived from the sequence name by adding an extension according to the {@FileNamingConventions} class.

• [-ar, --aperture-radius], double, required, Radius of the beam region [m].
• [-br, --ball-radius], double, required, Ball radius [m]. The radius of the balls filling the volume must be bigger than the aperture radius. The user must be careful not to make the ball radius too big, otherwise the point sources will be too close to the balls or will be inside of them. The sources can not be inside the balls. When the sources are too close to the balls, the field expansion will require higher degree spherical harmonics which will make the field map slower and bigger or even impossible to achieve the required accuracy. The quality of the field map can be checked by setting the --statistics option of the 'expand-single-row' command true.

 

Usage: create-straight-path [OPTIONS]...

Creates a straight path for tiling the boundary surface around an accelerator element. This path usually represents the design orbit through the element. The points in the path determine the longitudinal positions of the transverse profiles, which themselves determine the tiles of the boundary surface. This is a utility command. The path can be created by other means as well, for example a spreadsheet.

• [-sx, --start-x], Double, required, X coordinate of the line starting point.
• [-sy, --start-y], Double, required, Y coordinate of the line starting point.
• [-sz, --start-z], Double, required, Z coordinate of the line starting point.
• [-ex, --end-x], Double, required, X coordinate of the line end point.
• [-ey, --end-y], Double, required, Y coordinate of the line end point.
• [-ez, --end-z], Double, required, Z coordinate of the line end point.
• [-n, --name], String, required, The name of the element for which the path is created. The path file name will be constructed from this using the file naming conventions. Such as: "elementname-PATH.txt"
• [-ns, --number-of-steps], Integer, required, The number of steps in the path. This number determines the longitudinal density of the surface points surrounding the beam region. This influences the accuracy of the reconstruction of the field of the element.

 

Usage: create-tiling-config [OPTIONS]...

Creates a tiling configuration object. The tiling configuration contains information describing the tiling of the boundary surface around an accelerator element. The tiling is used for determining the strength of the point sources which reconstruct the field of the element. The tiling parameters are determined by the geometry of the element and the desired accuracy of the field reconstruction. The tiling configuration is used the following commands: 'write-surface-points', 'check-field','create-acc-element', 'create-checkpoint-file'

• [-n, --name], String, required, The name of the element. Several input and aoutput files will be created from this name using the file naming conventions.
• [-p, --profile], Profile, required, A profile to be extruded. Profile describes the cross section of the element at a particular point along the path ot the element, which is usually the design orbit. The profile can be created by the 'create-rect-profile' or 'create-ellipse-profile' commands.
• [-lu, --length-unit], String, required, Length unit used in the input files: [mm, cm or m]. In SIMPA the length unit is in meters, however the input files for the field solver software (COMSOL, OPERA, etc.) used for getting the field values on the reference point on the boundary surface may use different units. This length unit parameter specifies what unit the data in those files written by SIMPA will be. The commands taking into account this information.
• [-e, --elevation], double, required, Elevation of the point sources above the boundary surface of the element. This parameter is important for several reasons. The elevation should be chosen such that the point sources are not too close to the boundary surface of the element. The point sources can not be inside the balls of the cover. When the sources are too close to the balls, the field expansion will require higher degree spherical harmonics which will make the field map slower and bigger or even impossible to achieve the required accuracy. On the other hand, when the sources are too far from the boundary surface, the solving of the strengths of the point sources will be difficult, because the matrix describing the linear system will be ill-conditioned. As a rule of thumb the elevation should be about the same as the distance between the points on the boundary surface. The elevation should be given in meters.
• [-o, --output-format], String, Output format for commands generating files for field solver software (COMSOL, OPERA, etc.). The default is "opera3d", other option is "txt". These are almost the same except the OPERA3D format has header lines.
• [-s, --scaling], double, required, Scaling factor.
• [-tt, --tile-type], String, The type of the tile: 'rectangular' or 'triangular'. The default is 'rectangular'. Certain surfaces can not be tiled with rectangular tiles, for example a bended tube. In this case the triangular tiling should be used.
• [-ft, --field-type], String, required, The type of the field: 'se' for static electric field or 'sm' for static magnetic field. When the filed type is electric, the sources around the boundary surface are electric point sources. When the field type is magnetic, the sources are magnetic point sources. Magnetic point sources are essentially tho perpendicular infinitesimally small wires oriented such that they are tangential to the boundary surface. The command 'create-acc-element' solves for the strengths of these point sources.

 

Usage: create-twiss [OPTIONS]...

Creates a Twiss parameters object. Usually the Twiss parameter are assigned to a variable and passed to the the 'create-beam' command. See also the 'twiss' and 'beam-twiss' commands.

• [-x, --hor-position], Double, required, The horizontal position of the particle or beam center [m] compared to the reference orbit.
• [-xp, --hor-angle], Double, required, The horizontal angle [rad].
• [-y, --ver-position], Double, required, The vertical position [m].
• [-yp, --ver-angle], Double, required, The vertical angle [rad].
• [-ha, --hor-alpla], Double, required, The horizontal alpha
• [-va, --ver-alpha], Double, required, The vertical alpha
• [-hb, --hor-beta], Double, required, The horizontal beta [m].
• [-vb, --ver-beta], Double, required, The vertical beta [m].
• [-hd, --hor-dispersion], Double, required, The horizontal dispersion [m].
• [-vd, --ver-dispersion], Double, required, The vertical dispersion [m]
• [-hdp, --hor-disp-prime], Double, required, The horizontal dispersion prime
• [-vdp, --ver-disp-prime], Double, required, The vertical dispersion prime

 

Usage: create-vacuum-chamber [OPTIONS]...

Creates a vacuum chamber by adding profiles at the specified distances from the local origin of the element, which is usually the center of the element, except for arbitrary elements. The vacuum chamber should be assigned to a variable which can be used later for inserting it into the sequence. Profiles can be created with the 'create-rect-profile' or 'create-ellipse-profile' commands.

• [-d, --distances], HashMap, required, A map with the profiles as keys and arrays of doubles with the distances from the local origin of the element as the values. The format of the map is: [{profile1:[dist1, dist2, ...]}, {profile2:[dist1, dist2, ...]} ...]

 

Usage: create-vector3d [OPTIONS]...

Create a Vector3D object. Usually the Vector3D objects are assigned to a variable and passed to other commands.

• [-x], double, required, X value [m].
• [-y], double, required, Y value [m].
• [-z], double, required, Z value [m].

 

Usage: end-sequence [OPTIONS]...

Finishes the sequence and saves the orbit to a file. Once the sequence is finished no elements can be added to it. The sequence can be made active by the 'use-sequence' command.

• [-o, --output], String, required, File to write the orbit to.
• [-lff, --local-frame-file], String, For non planar machines the local coordinates can be non-trivial. This option allows to write the local coordinates to a file in those cases and can be inspected or used for some other purpose. The local coordinates will be written into a file if this option is given.
• [-inc, --local-frame-increment], Integer, Increment option, which can be present only if the '--local-frame-file' option is given. The local frames will be written to the file every n-th orbit point, where n is the increment. For example: 1 takes all the orbit points, 2 takes every second, and so on, default is 5.
• [-lcf, --local-centers-file], String, If not null, the local origin of each element expressed in the global system will be written into the given file.

 

Usage: field-on-curve [OPTIONS]...

Writes the field of the elements in the given map or in the active sequence into a file. The values are taken along the reference orbit with an optional shift. If no map is given,it takes the map of the current sequence. It is usually used for checking the correctness of the field maps. In the output file the components of the fields are expresse in the global coordinate system.

• [-m, --map], Map, A map object with names of the binary field map files as keys and scaling factors as values. The format of the map is: [{"binary_filename1":scaling1, "binary_filename2":scaling2, ...}] Example:[{"BENDINGS_12.bin":-37.51} ,{"QFND_12.bin":3.243957}] If no map is given, it takes the map of the active sequence.
• [-s, --shift], Vector3D, Vector for a shift in the local frame from the reference orbit, if any. It can be created with the 'create-vector3d' command.
• [-o, --output], String, required, File to write output to.
• [-lf, --local-frame], Boolean, If true, the field is written in the local frame of the element. If false, the field is written in the global frame. Default is false.

 

Usage: insert-chamber [OPTIONS]...

NOT YET IMPLEMENTED. !!! You can use the various "add-..." commands instead with the vacuum chamber option at the creation of the sequence. Inserts a vacuum chamber into the sequence at the given position or the location of the given element.

• [-vc, --vacuum-chamber], Map, required, The vacuum chamber to be inserted.
• [-br, --element-name], BeamRegion, The name of the element which the vacuum chamber is inserted at. Should not be given if the longitudinal position is given.
• [-lp, --longitudinal-position], Double, The longitudinal position [m] along the reference orbit where the vacuum chamber is inserted. Counted from the beginning of the sequence. If the element name is given, this parameter is ignored.

 

Usage: java-call [OPTIONS]...

Executes a method from the given class in this Java virtual machine. This is useful to call small java programs from the SIMPA to process some results or do some other tasks. If the class is not in the classpath ( external),the file must be compiled with the same version of Java as SIMPA is running on or earlier. For external classes the class file must be in the working directory or in the directory specified by the --path option.

• [-cn, --external-class-name], String, External class name without .class extension.
• [-icn, --internal-class-name], String, Internal class name without .class extension. Example: "simpa.acc.api.utils.BeamSizeCalculator"
• [-p, --path], String, A path to the class file. It should be specified if it is not in the working directory. Example ../helperClasses/ Should not be confused with the java classpath.
• [-mn, --method-name], String, required, The name of the method to be called in the Java class. The signature of the method called is very general: Object someMethod(Object[] methodParameters) It is the responsibility of the user to make sure the number of the parameters, their type and order matches the method signature. The method can be static or non-static.
• [-mp, --method-parameters], Object[], required, An array of objects to be used as parameters for the method to be called. It is the user's responsibility to make sure the number of the objects, their type and order matches the method signature.
• [-cp, --constructor-parameters], Object[], An array of objects to be used as parameters for the constructor of the Java object, if any. It is the user's responsibility to make sure the number of the objects, their type and order matches the constructor signature.

 

Usage: line-optics [OPTIONS]...

Calculates linear optics of a transfer line by tracking two ellipse beams. The two beams must have some small momentum deviation to determine the dispersion. The trajectory of the particles in the beams pierces a series of observer disks along the reference orbit. There is a disk por each orbit point. The intersection points of the trajectory with the disks are used to fit phase-space ellipses at the disk. The Twiss parameters are calculated from the fitted ellipses. The command returns the Optics object and writes it to a file.

• [-b0, --beam-nominal], Beam, required, An ellipse beam with some momentum which is usually the nominal momentum.
• [-b1, --beam-dpop], Beam, required, An ellipse beam with a dp/p momentum deviation.
• [-ss, --step-size], Double, required, The step size [m] for the tracking.
• [-dr, --disk-radius], double, required, Observer disk radius [m]. Should be a bit bigger than the maximum aperture of the machine. One must be careful to not intersect th beam line more than once with the observer disk.
• [-f, --output-file], String, required, Output file name for the optical functions.
• [-bt, --backward-tracking], Boolean, If true tracking backward by inverting the momentum vector. False by default. To use this function the Twiss parameters at the end of the line must be known to calculate the optics of the full line.
• [-wt, --write-trajectory], Boolean, If true, writes two trajectory files to the disk corresponding to the two ellipse beams. Useful for debugging. False by default.

 

Usage: match [OPTIONS]...

Matches a line or a ring to the given target parameters. An active sequence must be selected. After the matching the scaling map of the active sequence will be updated with the best values of the scaling factors of the field maps. It returns a copy of this map of field maps and scaling factor for later use, if needed. This command can be used for ring or transfer line matching. In the latter case two beams must be given as input parameters. In the former case two particles are needed.

• [-b0, --beam0], EllipseBeam, An ellipse beam with the nominal momentum. Used for tracking during transfer line optics calculation.
• [-b1, --beam1], EllipseBeam, An ellipse beam with some dp/op momentum deviation. Used for determining the dispersion in transfer lines.
• [-p0, --particle0], Particle, A particle with the nominal momentum. Used for tracking during ring optics calculation.
• [-p1, --particle1], Particle, A particle with some dp/op momentum deviation. Used for determining the dispersion in rings.
• [-dr, --disk-radius], Double, required, Radius [m] of the observer disk for the tracking.
• [-ss, --step-size], Double, required, Step size [m] for the tracking.
• [-m, --matcher], Matcher, required, An matcher object to be used. See 'bobyqa-matcher', 'cmaes-matcher' commands.
• [-bt, --backward-tracking], Boolean, If true, tracking backward by inverting the momentum vectors in the beams. False by default. Useful for transfer lines when the end Twiss parameters are known.
• [-of, --optics-file], String, Writes the matched optics at the end of the matching into the given file.

 

Usage: matching-target [OPTIONS]...

Creates a target value for optics parameter matching. The target value is a scalar value of an optics parameter. The optics parameter is specified by its type and longitudinal position. The target value is the value of the optics parameter at the given longitudinal position. The target value can be weighted by a scalar value. The default weight is 1.0. The target should be assigned to a variable and passed to the matcher object. Instead of exact values minimum or maximum values can be also given. Those have no effect unless the given limit is reached.

• [-lp, --longitudinal-position], Double, Longitudinal position [m] of the optics parameter at which the matching performed.
• [-tt, --target-type], String, required, A string specifying the type of the matching target parameter. For example: "H_BETA", "V_DISPERSION", "H_PHASE_ADVANCE", etc. The complete list of the matching target types names can be found here: https://simpa-project.docs.cern.ch/simpa.acc/simpa/acc/api/match/MatchingTargetType.html
• [-tv, --target-value], Double, The target value of the optics parameter.
• [-ul, --upper-limit], Double, Upper limit of the optics parameter at the given longitudinal position.
• [-ll, --lower-limit], Double, Lower limit of the optics parameter at the given longitudinal position.
• [-w, --weight], Double, The weight of the matching target parameter. If not given the default value of the parameter type is taken, which is 1.0.

 

Usage: matching-variable [OPTIONS]...

Creates a variable for optics parameter matching. It is a scaling factor belonging to a field map, which will be varied during the matching.

• [-fm, --field-map], String, required, The full file name of the field map with extension.
• [-min, --min-value], Double, The minimum value of the scaling factor. This value is in most cases is the limit of the power supply connected to the accelerator element.
• [-max, --max-value], Double, The maximum value of the scaling factor. This value is in most cases is the limit of the power supply connected to the accelerator element.
• [-g, --guess], Double, Initial guess for the scaling factor of the field map. This can be important when the BOBYQA matcher is used. The initial guess should be close to the global optimal value, because this matcher can be stuck in a local optimum. If not given, the value is taken from the scaling map of the active sequence.

 

Usage: mirror-path [OPTIONS]...

Mirrors path points in the given file. The path assumed to start from the origin (0,0,0). It finds automatically the plane for mirroring XY, XZ or YZ. This is a utility command for creating a full path from a half path to have an exactly symmetric path.

• [-i], String, required, The input file containing a half-path. This is just a list of X, Y, Z coordinates in each line. The path should start from the origin (0,0,0).
• [-o], String, required, The output file containing a full path.
• [-u], String, Length unit of the input file. If given, the output will be scaled accordingly to meters. This is needed for example when when the half path is obtained from COMSOL or OPERA and the units are not meters as in SIMPA. Path in SIMPA is given in meters.

 

Usage: orbit-at-bpms [OPTIONS]...

Saves the orbit at the beam position monitors in the sequence. The optics must be calculated before using this command. This is useful to feed the orbit into orbit corrector software like YASP at CERN.

• [-hpf, --h-position-file], String, Output file in which the relative (to the reference orbit ) positions at each horizontal BPM will be written to.
• [-vpf, --v-position-file], String, Output file in which the relative (to the reference orbit ) positions at each vertical BPM will be written to.

 

Usage: resample-path [OPTIONS]...

Re-samples the given path with the given number of steps or a list of distances given in meters from the first path point. This is a utility command which can be used for example to pick specific longitudinal positions from a path to provide a path suitable for tiling a boundary surface.

• [-i, --input-file], String, required, The input file containing a original path.
• [-o, --output-file], String, required, The output file containing the re-sampled path.
• [-s, --steps], Integer, The number of steps to have after the re-sampling.
• [-d, --distances], Double[], A list of distances from the first path point. The distance should be given in the same units as the input file.
• [-fx, --force-x], Double, Forces the X coordinate to the given value. Useful to remove small errors.
• [-fx, --force-y], Double, Forces the Y coordinate to the given value. Useful to remove small errors.
• [-fx, --force-z], Double, Forces the Z coordinate to the given value. Useful to remove small errors.

 

Usage: ring-optics [OPTIONS]...

Calculates linear optics of a ring by tracking two particles. The two particles must have some small momentum deviation to determine the dispersion. The trajectory of the particles pierces a series of observer disks along the reference orbit. There is a disk for each orbit point. The intersection points of the trajectory with the disks are used to fit phase-space ellipses at each disk. The Twiss parameters are calculated from the fitted ellipses.

• [-p1, --particle1], Particle, required, A particle with some momentum usually the nominal momentum.
• [-p2, --particle2], Particle, required, A particle with some momentum deviation compared to particle 1. The momentum deviation is used for dispersion calculation.
• [-ss, --step-size], Double, required, The step size [m] for the tracking.
• [-dr, --disk-radius], double, required, Observer disk radius [m]. Should be a bit bigger than the maximum aperture of the machine. One must be careful to not intersect the ring more than once with the observer disk.
• [-f, --output-file], String, required, Output file name for the optical functions.
• [-t, --turns], Integer, Number of turns for the tracking, default is 64. It must be a power of two for the NAFF algorithm to calculate the tunes.
• [-wt, --write-trajectory], Boolean, If true, writes a trajectory file to the disk during the tracking. Useful for debugging. False by default

 

Usage: sequence-sources-to-file [OPTIONS]...

Writes all sources in the sequence to a file. This is useful for checking if any source is inside the aperture of the sequence, or even more importantly inside any ball of the covering, which should not happen.

• [-f, -file], String, required, The file where the source coordinates will be written.

 

Usage: set-integrator [OPTIONS]...

Sets symplectic integrator. to be used for the tracking. At the moment there is only one which is Tao's symplectic integrator. See: https://arxiv.org/abs/1609.02212

• [-om, --taos-omega], Double, required, The omega for Tao's symplectic integrator. A value betewen 0..2PI, need to experiment with it a bit to get the best value.

 

Usage: set-scalings [OPTIONS]...

Sets the scalings of accelerator element groups.There must be an active sequence selected before using this command.

• [-m, --map], Map, required, A map object with the with names of the binary field map files as keys and scaling factors as values.
• [-ee, --enable-external], Boolean, If true, the scaling map can contain field maps not in the sequence, no checking will be made. Foreseen for external disturbances. False by default.

 

Usage: survey [OPTIONS]...

Writes a file with elements centers in the CERN coordinate system. The active sequence will be used. It is intended for sequence checking against MAD-X survey command output. The command parameters have the same name and meaning as the MAD-X command. See MAD-X manual p. 13.

• [-x, --x0], Double, required, Initial X0 coordinate in the CERN coordinate system.
• [-y, --y0], Double, required, Initial Y0 coordinate in the CERN coordinate system.
• [-z, --z0], Double, required, Initial Z0 coordinate in the CERN coordinate system.
• [-th, --theta0], Double, required, Initial theta angle in the CERN coordinate system.
• [-phi, --phi0], Double, required, Initial phi angle in the CERN coordinate system.
• [-psi, --psi0], Double, required, Initial psi angle the CERN coordinate system.
• [-f, --file], String, required, File to be written.
• [-en, --element-name], String, The name of the element at which the coordinates and angles are given. If not specified, by default the beginning of the sequence is taken.

 

Usage: system-call [OPTIONS]...

Call the given Linux command and returns the exit code.

• [-c, --command], String, required, A command string between double quotes to be executed. For example: system-call -c "ln -s ../elements/quad-SOLUTION.txt quad-SOLUTION.txt"

 

Usage: track [OPTIONS]...

Tracks a particle or a beam. Either a particle or a beam must be given, but not both.

• [-p, --particle], Particle, A particle to be tracked. Either a particle or a beam must be given, but not both.
• [-b, --beam], Beam, A beam to be tracked. Either a particle or a beam must be given, but not both.
• [-tu, --turns], Integer, required, Number of turns to be tracked in case of a ring. For transfer lines this parameter must be 1.
• [-ss, --step-size], Double, required, The step size for the tracking [m]
• [-phop, --observer-position], Double[], List of longitudinal positions [m] of the phase space observers along the reference orbit. If not given, by default one is added at position zero in rings. For transfer lines there is also a second one at the end by default. Giving an empty list the default observers will be removed.
• [-dr, --disk-radius], Double, required, Radius [m] of the observer disks. Should be a bit bigger than the aperture of the ring or beam line. It should not intersect is twice however.
• [-to, --trajectory-observer], Boolean, If set true, a trajectory observer will be added. Be careful, the trajectory file can be huge when a bunch with a large number of particles is tracked. For this reason when a bunch is tracked in a ring no trajectory observer is allowed. For single particle it can be used both in rings and transfer lines. False by default.
• [-df, --debug-field], Boolean, If set true, the output of a trajectory observer will contain also the value of the fields at the position of the particle. Single particle tracking only, for beams it has no effect.
• [-th, --threads], Integer, The number of threads to be used for the beam tracking. All available threads minus 2 used by default.
• [-bt, --backward-tracking], Boolean, If true tracking backward by inverting the momentum vector. The output files of the phase space observers will include the string '-BACKWARD-' See {@link FileNamingConventions}. False by default.

 

Usage: transform-acc-element [OPTIONS]...

Transform an accelerator element with the given rotation and translation. This is useful when elements which are different only in their orientation are added to the sequence. Technically the solution file containing the sources will be transformed.

• [-n, --name], String, required, The name of the element.
• [-r, --rotation], Rotation, The rotation to be applied, before the translation if any. See the 'create-rotation' command.
• [-t, --translation], Vector3D, A translation vector to be applied after the rotation if any. See the 'create-vector3d' command.
• [-ir, --inverse-rotation], Boolean, If true, the inverse of the rotation will be applied. False by default.
• [-it, --inverse-translation], Boolean, If true, the inverse of the translation will be applied. False by default
• [-on, --output-name], String, Name for the transformed element. If not given the original solution file will be replaced and a copy of the original solution file will be written. Example:elementname-SOLUTION.txt.original

 

Usage: twiss [OPTIONS]...

Calculates and prints the Twiss parameters from a phase space coordinate file produced by tracking a single particle in a ring. It returns an object containing the Twiss parameters which can be assigned to a variable and used later as input for other commands, for example the 'create-beam' command. The Twiss parameters are calculated by fitting an ellipse to the phase space coordinates.

• [-f, --file], String, required, Phase space file which is used as input for the calculation.

 

Usage: update-scalings [OPTIONS]...

Update the scalings of the active sequence. Scalings in the given update map which are not in the sequence map already will be ignored. Scalings in the original map of the sequence which are not in the update map are not modified.

• [-m, --map], Map, required, A map object with the names of the binary field-map files as keys and scaling factors as values.

 

Usage: use-sequence [OPTIONS]...

Sets the sequence to be used. Many commands require the active sequence to be defined.

• [-n, --name], String, The name of the sequence. Beforehand, the sequence with this name must be created by the 'create-sequence' command.

 

Usage: write-surface-points [OPTIONS]...

Writes a file with the coordinates of the surface points on the boundary of the accelerator element according to the given configuration. This file is usually used as input for electro-magnetic software the get out the field values at the points in this file.

• [-tc, --tiling-config], TilingConfig, required, Tiling configuration created with the 'create-tiling-config' command. The tiling configuration contains the element name which is used for naming the output file according to the file naming conventions, see: https://simpa-project.docs.cern.ch/constant-values.html#simpa.core.api.FileNamingConventions.POINTS_FILE_EXTENSION