7.83 undulator_brightness

• type: setup command.
• function: compute the on-resonance brightness of a planar undulator using R. Lindberg’s analytic Gaussian-beam formula and expose the result as an RPN scalar. The scalar is refreshed every time the Twiss parameters are recomputed — including each evaluation of the optimization function — so the value tracks lattice changes and can be used directly as an optimization target.
• Command syntax, including use of equations and subcommands, is discussed in 7.2.

The command may be issued multiple times to register multiple undulator brightness probes (different photon energies, different undulators, different observation points in the lattice). Each registration creates an RPN scalar named <tag>.brightness, distinguished by the user-supplied tag (same naming convention as rpn_load). Until the first twiss_output runs, the scalar holds the value 0.

The deflection parameter K is not a namelist input. It is derived at every evaluation from the undulator resonance condition

(17)

using γ obtained from Pref_output (which is γβ) at the chosen Twiss source element, n from harmonic, λ_u from period_length, and λ from either wavelength or photon_energy. If the requested wavelength is below the fundamental at K=0, the spec warns once and leaves the RPN scalar at its previous value.

Beam parameters (the (ϵ,β,α,η,η′,σ_δ) tuple for each plane) are first reduced to their dispersion-corrected effective values before being passed to the brightness routine, so the dispersion fields etax, etaxp, etay, etayp are functional inputs, not ornamental.

• tag — Required. Short label prepended to the RPN scalar name: the brightness is stored as <tag>.brightness. Tags must be unique across all undulator_brightness registrations.
• wavelength — Photon wavelength in meters. Exactly one of wavelength and photon_energy must be greater than zero.
• photon_energy — Photon energy in keV. Internally converted to wavelength via λ = 12.39841984 × 10^-10m∕E[keV].
• harmonic — Odd harmonic number n at which the brightness is evaluated. Default 1.
• detuning — Scaled detuning Δλ∕λ = (2πN∕n)detuning fed through to Lindberg’s formula as radDet. Good choices are 0 (on resonance), -0.5 (default, near the flux maximum), or -1 (broader peak).
• period_length — Required. Undulator magnetic period λ_u, meters.
• n_periods — Number N of magnetic periods. The total undulator length used in the brightness calculation is Nλ_u. Either n_periods or total_length must be supplied (with total_length taking precedence when both are given).
• total_length — Optional total length of the undulator, meters. When greater than zero, the period count is derived as

  (18)

  and the brightness is evaluated for an undulator of length Nλ_u (i.e. truncated to a whole number of periods). If n_periods is also set to a different value, the derived N overrides it and a warning is issued. If total_length is less than one period_length, the run is aborted.

• current — Required. Stored beam current, amperes.
• use_twiss_output_values — If nonzero, the beam emittances, optical functions, and energy spread are taken from the live Twiss / radiation-integrals state at the Twiss source element described below. The explicit beam-parameter fields (emitx, …, Sdelta) are ignored in this mode. Requires coupling > 0 and a prior &twiss_output invocation with radiation_integrals = 1.
• coupling — Required when use_twiss_output_values=1. Transverse coupling parameter κ used to split the natural emittance computed from radiation integrals:

  (19)

  with damping partition numbers J_x,J_y taken from the radiation-integrals structure of the beamline.

• twiss_element — Optional element name marking the location at which the Twiss source values (β_x,y,α_x,y,η_x,y,η′_x,y) and γ are evaluated. Defaults to the last element of the beamline. The element need not be a MARK — any element with valid Twiss data may be used (in use_twiss_output_values=1 mode, ϵ_x,y and σ_δ remain ring-averaged quantities from the radiation integrals).
• twiss_occurence — 1-based occurrence index of twiss_element in the expanded beamline. Ignored if twiss_element is blank. Default 1. Note that "occurence" is deliberately misspelled to be consistent with historical usage in the interface.
• emitx, emity — Horizontal and vertical geometric emittances, meters⋅radian. Used only when use_twiss_output_values=0. emitx must be positive; emity may be zero (round beam not supported by the underlying formula, but values down to the diffraction limit are fine).
• betax, alphax, betay, alphay — Twiss parameters at the undulator center, used only when use_twiss_output_values=0. betax and betay must be positive.
• etax, etaxp, etay, etayp — Dispersion and its derivative at the undulator center. Used only when use_twiss_output_values=0. These contribute to the brightness via the dispersion-corrected effective beam parameters; pass zero if dispersion is negligible at the observation point.
• Sdelta — RMS relative energy spread σ_δ = σ_E∕E. Used only when use_twiss_output_values=0. Must be positive.

The reported brightness is in conventional accelerator units of photons / s / 0.1% BW / mm² / mrad².