7.41 modulate_elements

• type: setup command.
• function: define parameters for time-dependent modulation of elements
• sequence: must follow run_setup.
• N.B.: if the ramped element is modeled with a matrix, a significant performance hit may be seen. It is best to use symplectic variants of the elements, since these don’t invoke the matrix calculation.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

N.B.: This command will produce unpredictable results when used with error_element, alter_elements, and load_parameters (except when change_defined_values=1). It should work properly with link_elements in turn-by-turn mode when the source element is modulated, but not when the target element is modulated.

• name — A possibly-wildcard-containing string giving the names of the elements to modulate. If not specified, then one must specify type.
• item — The name of the parameter to modulate.
• type — A possibly-wildcard-containing string giving the names of element types to modulate. May be specified with name or by itself.
• expression — RPN expression for the modulation amplitude A. The value of the time is on top of the stack.
• filename — Name of SDDS file from which to read modulation data, if expression is not used.
• time_column — Name of column in filename giving time data for the modulation table.
• convert_pass_to_time — By default, the mean arrival time of the beam is used to compute the time value for computing the modulation amplitude. If the arrival time vales are offset by CHANGE_T=1 on RFCA elements, this won’t work as desired. In that case, one can compute the time from the pass number and the position of the element within the lattice.
• amplitude_column — Name of column in filename giving amplitude data for the modulation. Together, time_column and amplitude_column define a function A(t).
• refresh_matrix — Frequently there is a matrix associated with an element even if tracking through the element does not use the matrix. In this case, elegant doesn’t normally update the matrix for the element as it modulates the element, since that may involve a significant time penalty. If this parameter is set to a non-zero value, the matrix will be updated. For elements that use a matrix for tracking, the matrix is always updated.
• differential, multiplicative, factor — Determine how the amplitude function A(t) is used to obtain the new value of the parameter vs time v(t). There are four cases
  • differential=1, multiplicative=0: v(t) = v₀ + fA(t) (default).
  • differential=0, multiplicative=0: v(t) = fA(t).
  • differential=1, multiplicative=1: v(t) = v₀ + v₀fA(t).
  • differential=0, multiplicative=1: v(t) = v₀fA(t).

  where v₀ is the original value and f is the factor. The factor is convenient when A(t) is from a file and one wants to quickly change the amplitude of the modulation but not its shape.

• start_pass, end_pass — Specifies the starting and ending pass between which the modulation will be applied.
• pass_delay, time_delay — Specifies pass- and time-based delay of the modulation function. When given, equivalent to changing the time value t that is used for function evaluation to t - P_dT₀ - T_d, where P_d is the pass delay, T₀ is the revolution time, and T_d is the time delay.
• start_occurence, end_occurence — If nonzero, these give the starting and ending occurrence numbers of elements that will be modulated. N.B.: if wildcards are used, occurrence number counting is for each set of identically-named elements separately, rather than for the sequence of matched elements.
• s_start, s_end — If non-negative, these give the gaving and ending position limits for the end-of-element locations of elements to be modulated.
• after — The name of an element. If given, the modulation is applied only to elements that follow the named element in the beamline.
• before — The name of an element. If given, the modulation is applied only to elements that precede the named element in the beamline.
• verbose — If nonzero, information is printed to the standard output as changes are made. Use for debugging only, since otherwise it may slow the simulation.
• verbose_threshold — If nonzero, verbose information is printed only when the fractional change exceeds the given value.
• record — Gives a possibly incomplete filename to which will be written a record of the values of the modulation.
• flush_record — Gives the interval in steps at which to flush the record file. Higher values result in less frequent updates to the record, but may improve performance.