7.43 load_knobs

• type: setup command.
• function: load knob definitions from an SDDS file. A knob is a virtual scalar variable whose value V drives a fixed linear combination of element parameters: setting V offsets each linked (element,parameter) pair by (V - V _prev) ⋅ Factor, so the lattice carries the cumulative contribution of every knob. Knobs can be the target of &vary_element, &optimization_variable, and &error_element in place of a real element.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

Input file format. The file must contain one string parameter (KnobName) and three required columns and one optional column:

• ElementName (string) — the element to drive. Wildcards are supported and expanded at load time using the same wfind_element/expand_ranges idiom as &alter_elements.
• ElementParameter (string) — the parameter of that element to drive.
• Factor (numeric) — the per-unit-of-V offset applied to that parameter.
• ElementOccurence (long, optional) — when present, each row is resolved to the unique element matching both ElementName and the given occurence value (1-based, the same value used in parameter_output). This permits the same ElementName to repeat within a page with different occurence values. Wildcards in ElementName are not permitted when ElementOccurence is supplied; such rows are rejected at load time. (Note the elegant spelling: “occurence”, single r.)

Each page of the file defines one knob. The page’s KnobName parameter is the knob’s name and must be unique across all &load_knobs invocations (case-insensitive; names are upper-cased internally).

Each registered knob is initialized with V =0 and exposed as the RPN scalar <KnobName>.value, which tracks the knob’s current value across all subsequent &vary_element, &optimization_variable, and &error_element activity.

Referencing a knob. In &vary_element / &optimization_variable / &error_element, set name=<KnobName> (the item= slot is ignored and may be omitted). The value the command produces is assigned directly to V ; the linked element parameters update by the delta times their respective Factor values. When several knobs touch the same element parameter, their contributions sum naturally (each knob’s update is delta-from-previous, so the lattice state at any time is p = p₀ + ∑ _jV _j ⋅ F_j).

Notes and limitations (v1).

• &vary_element modes multiplicative and differential are rejected for knob targets (the knob’s intrinsic “current value” is the additive scalar V ).
• &error_element with a knob target is always additive on V ; the fractional and nonadditive modifiers do not apply. The error log does not record knob deltas in v1; element parameters themselves carry the cumulative effect and can be inspected via parameter_output.
• &save_lattice does not bake the converged knob value into the saved element definitions. Re-issue &load_knobs (and re-set the knob values) after reloading.

Parameters.

• filename — Required. Path to the SDDS file described above. Subject to the usual compose_filename/search_path resolution.
• verbose — If nonzero, prints one line per loaded knob with the number of (element, parameter) targets after wildcard expansion.