Shot review

DEFAULT_CLEARANCE_THRESHOLDS

Status tiers of clearance (engineering defaults, not facility criteria): :fail above 1e12 W/cm² (plasma formation) or 1e-3 of the beam power on a component, :review above 1e9 W/cm² (ablation and debris onset) or 1e-5.

BeamEnvelope(beam; intensity, peak_fraction, enclosed, margin = 0.0)

Geometric beam envelope: at axial distance s from best focus, the best-focus contour ellipse (see envelope_radius) grown by the f-cone radius |s|/(2F) and a uniform margin (mm). In geometric optics with a phase plate (every lens point fills the whole spot), the intensity at a point is the mean of the focal intensity over a disk of radius |s|/(2F), so outside the envelope it is below the contour level at every s. Clearance is the signed distance to the envelope; negative means inside.

ClearanceReport

Result of clearance: one ClearanceRow per beam and hardware component plus the envelope, error-set and threshold settings. See violations, min_clearance. canceled is true when a clearance callback stopped the check early; rows then hold only the beams completed before the cancel (the leading beams, in input order).

ClearanceRow

One beam/hardware-component pair. "Worst" values are over the error set (pointing, target offset, hardware tolerance, focus):

• clearance — worst-case signed distance to the beam envelope (mm; negative = overlap)
• nominal — the same at nominal pointing and focus
• point, s — hardware point of minimum clearance and its axial position from best focus (mm)
• power, intercepted — worst-case power (TW) on the component (core + wings) and its fraction of the beam power
• peak_intensity — worst-case beam intensity (W/cm², normal to the beam, core + wings) at the component's upstream surface points, ignoring shadowing
• status — :fail, :review or :pass against the report's thresholds

PowerLawWing(fraction; rh = :r95, rmax = 1.5)

Halo with I ∝ [1 + (r/rh)²]^(-3/2) for r ≤ rmax, carrying fraction of the beam power. rh = :r95 uses the radius enclosing 95% of the core (geometric mean of the axes). rmax is the spatial-filter cutoff (NIF ≈ ±200 µrad × 7.7 m ≈ 1.5 mm).

SpotWing

Supertype of low-level circular far-field components outside a beam's phase-plate core, used only by clearance checks (they carry ≲1% of the energy and do not matter for drive symmetry). Each wing is centered on the beam axis at best focus; radii in mm.

UniformScatter(fraction; radius = 23.0)

Far-angle scatter floor: fraction of the beam power spread uniformly over a disk of radius mm at the target plane (NIF final-optics scatter up to ≈3 mrad × 7.7 m).

beam_component_power(op, beams) -> Matrix

Absorbed power (TW) per beam (rows) and component (columns), both sides of each component, from the deposition operator. Beams may differ from the operator's in pointing, focus, spot and power; each is matched to the operator by its port.

clearance(target, beams; targets, hardware = all other surfaces,
          intensity = nothing, peak_fraction = 1e-4, enclosed = nothing,
          wings = nif_wings(), pointing = 0.05, target_offset = 0.025,
          hardware_tolerance = 0.0, focus = 1.0, margin = 0.0, ssd = 0.0,
          thresholds = DEFAULT_CLEARANCE_THRESHOLDS, nangles = 16, level = 2,
          op = nothing, nspot = 61, callback = nothing,
          batch = Threads.nthreads()) -> ClearanceReport

Beam-to-hardware clearance check, judged on the worst case over an error set.

Spot. Each beam's SuperGaussianSpot core (with its optional super-Gaussian halo) plus clearance-only circular wings (default nif_wings(): a 1% power-law halo and a 10⁻³ scatter floor — engineering defaults, override with measured far fields). ssd (mm) is the half-width of the SSD smear along the dispersion axis, added isotropically to the envelope (conservative).

Envelope. The best-focus contour at an absolute intensity (W/cm²), a peak_fraction of the core peak, or an enclosed core fraction (give one), grown by the f-cone, ssd and margin. With wings, each spot component's contour is taken at the threshold divided by the number of components, and the envelope is their union, so the total intensity outside it is below the threshold.

Error set. Transverse errors add linearly (not in quadrature): R = pointing + target_offset + hardware_tolerance (mm) — per-beam pointing (NIF 50 µm rms spec; pass ≈ 0.12 for a 3σ statistical radius), rigid target offset (NIF mean beams-to-target ≈ 25 µm), and as-built hardware tolerance (metrology, or 0.1–0.25 mm without it). focus is the ± focal-position error (mm; 1994 NIF spec ≤ 1 mm). Worst-case clearance is exact: nominal − R − focus/(2F). Worst-case power and intensity are maxima over aims displaced to nangles points on the radius-R circle (plus nominal) at focus offsets 0, ±focus.

Status. thresholds (W/cm² and fraction of beam power): :fail above fail_intensity (1e12, plasma formation) or fail_fraction (1e-3), :review above review_intensity (1e9, ablation/debris onset) or review_fraction (1e-5). These are engineering defaults; NIF (TaLIS/BLIP) and LLE review criteria are not public.

Only hardware upstream of each beam's landing is checked: where the beam axis first meets one of the targets components (the surfaces the beam should hit), or the aim plane if it misses them. Hardware is sampled at triangle vertices and 4^level sub-triangle points. Power on hardware comes from the reference ray trace (nspot grid per core component; wings on equal-power polar grids), or for the core from op, a DepositionOperator for these ports, when given.

Progress and cancel. With a callback, beams are checked in batches of batch (input order) and callback((; done, total)) is called with the number of beams completed — once with done = 0 before any work, then after each batch. Returning true cancels: clearance returns at once with the rows of the completed beams and canceled = true in the report (a true after the last batch is ignored). The callback always runs on the calling task, never on a worker thread, so it may touch task-local state; it must not block for long, since no work runs while it does. Rows do not depend on callback or batch.

enclosed_radius(order, fraction)

Radius (in units of the 1/e semi-axes) of the super-Gaussian contour enclosing fraction of the power: the fraction inside ρ is P(2/n, ρⁿ) (regularized lower incomplete gamma function). For spots with a halo use envelope_radius.

envelope_distance(env, x) -> (distance, s)

Signed distance (mm) from point x to the beam envelope in the plane through x normal to the beam, and the axial position s of that plane relative to best focus.

envelope_radius(spot, power; intensity = nothing, peak_fraction = nothing,
                enclosed = nothing) -> ρ

Best-focus contour radius in units of the core 1/e semi-axes (halo included), set by exactly one of: an absolute intensity (W/cm²), a fraction of the peak focal intensity peak_fraction, or the enclosed power fraction. Returns 0 if the whole spot is below an intensity threshold.

min_clearance(report) -> Dict{Symbol,ClearanceRow}

Closest beam (worst-case clearance) for each hardware component.

nif_wings(; halo = 0.01, rmax = 1.5, scatter = 1e-3, scatter_radius = 23.0)

Default NIF clearance wing model. These are engineering defaults (see reference/research-notes.md), not facility criteria; override them with measured far-field data:

• a 1% power-law halo (OMEGA measured < 1% outside the super-Gaussian; the NIF/LMJ design specs allowed 2% outside the nominal spot), truncated at the spatial-filter angle;
• a 10⁻³ uniform scatter floor out to 3 mrad.

violations(report; status = (:fail, :review), clearance = -Inf) -> Vector{ClearanceRow}

Rows whose status is in status, or whose worst-case clearance is below clearance mm; failures first, then by clearance.

write_clearance_csv(path, report)

Write every row of a clearance report as CSV.

ApertureKeepOut(target; apertures = planar aperture components, peak_fraction = 0.01,
                intensity = nothing, pointing = 0.05, target_offset = 0.025,
                hardware_tolerance = 0.0, focus = 1.0, margin = 0.0,
                minimum = 0.0, weight = 100.0, nrim = 96)

Keep-out constraint for beams entering through circular apertures (laser entrance holes). aperture_clearance(keepout, beams) gives each beam's worst-case clearance (mm) from the rim of its entrance aperture — the aperture on the beam's port side — judged as clearance judges it: the beam envelope is the best-focus contour at peak_fraction of the peak (or at intensity, W/cm²) grown by the f-cone radius |s|/(2F) and margin; the clearance is the smallest distance from nrim rim points to the envelope, less the transverse error radius pointing + target_offset + hardware_tolerance and focus/(2F) for the focus error. The rim is the circle through the aperture mesh's outermost vertices.

The distance to the envelope ellipse is first order (Sampson): exact on the envelope and for round spots, and smooth in aim, defocus and spot size. Confirm a design with clearance, which also accounts for wings and power on hardware. Pass it as keepout to symmetry_objective or asymmetry_objective, which then add weight × Σᵢ max(0, minimum − cᵢ)².

SphereKeepOut(target; spheres = components on a `SphereSurface`, peak_fraction = 0.01,
              intensity = nothing, pointing = 0.05, target_offset = 0.025,
              hardware_tolerance = 0.0, focus = 1.0, margin = 0.0, minimum = 0.0,
              weight = 100.0)

Keep-out constraint for spherical obstacles inside a target, such as the capsule of a hohlraum. sphere_clearance(keepout, beams) gives each beam's worst-case clearance (mm) from the nearest of the spheres it passes before landing, with the envelope and error set of ApertureKeepOut: the distance from the sphere's center to the beam envelope (best-focus contour at peak_fraction of the peak, or at intensity, grown by the f-cone at the center's axial position and by margin) less the sphere's radius, the transverse error radius pointing + target_offset + hardware_tolerance and focus/(2F). The distance to the envelope is first order (Sampson), as for apertures; the f-cone tilt of the envelope surface (cos of the cone half-angle) is neglected.

A sphere counts only when its center lies upstream of where the beam axis first meets another opaque component (the wall a hohlraum beam lands on), found on the nominal beam; a sphere behind that surface is shadowed and ignored. The penalty added by the objectives is weight × Σᵢ max(0, minimum − cᵢ)². The deposition penalty direct (squared fraction of power on the capsule) vanishes as the spot edge starts to clip and cannot keep a margin; use this keep-out when the capsule must stay clear. Confirm with clearance on the capsule.

aperture_clearance(keepout, beams) -> Vector

Worst-case clearance (mm) of each beam from the rim of its entrance aperture (see ApertureKeepOut); Inf for a beam with no aperture on its port side. Differentiable in the beams' aim, defocus and spot size.

sphere_clearance(keepout, beams) -> Vector

Worst-case clearance (mm) of each beam from the spheres of a SphereKeepOut it passes before landing; Inf for a beam that passes none. Differentiable in the beams' aim, defocus and spot size.

UnconvertedColor(name; footprint, edge, focal_shift)

Unconverted-light footprint of one color at the 3ω best-focus plane: a square of side footprint (mm) whose nearest edge lies edge mm from the 3ω aim point, displaced in a port-dependent direction; its focus lies focal_shift mm beyond the 3ω focus.

UnconvertedReport

Result of unconverted_light_check: per-beam/color/component rows, plus per-component zone flags (nearest distance to TCC within zone_radius) and flat flags (planar components, which violate the NIF curvature rule inside a 1ω footprint unless dimpled: 1D curvature radius ≤ 2 mm or 2D ≤ 5 mm).

UnconvertedRow

beam, color, component, exposure (:exposed — hardware inside the footprint for a known offset direction; :possible — inside the footprint for some offset direction when the direction is unknown; :clear), and distance: the smallest transverse distance (mm) from the footprint region to the component (negative inside).

nif_unconverted()

NIF 1ω and 2ω footprints (NIF User Guide §4.5, §5.6.1): 1ω ≈ 22 mm square with nearest edge ≈ 4.8 mm from the 3ω aim point, 2ω ≈ 12 mm square with nearest edge ≈ 2.9 mm. Focal shifts: 1ω +460 mm (MacFarlane 2003); 2ω ≈ +270 mm (derived from fused-silica dispersion — see reference/research-notes.md).

unconverted_light_check(target, beams; colors = nif_unconverted(), offsets = nothing,
                        hardware = all surfaces, zone_radius = 32.0, level = 1)

Check target hardware against unconverted-light footprints. Footprints are prisms along each beam through its square footprint at the 3ω focal plane (near TCC the converging 1ω/2ω beams change size by ≲ 2% per cm, so the prism is a close approximation; shadowing is ignored, so exposure is conservative).

offsets maps beam names to the footprint offset direction: an angle (degrees, from the port's θ̂ toward φ̂, in the focal plane) or a 3-vector. The per-port directions are not public; without them every azimuth is considered and hardware is reported as :possible when any offset direction would expose it.

Also reports components within zone_radius mm of TCC (where unconverted light reaches) and planar components (flagged against the NIF curvature rule).

TALIS_OUT_OF_SCOPE

Requirements of the TCC Configuration Requirements document that talis_check does not evaluate, because Briareus has no model of the hardware involved.

Source of the rules implemented by talis_check.

TaLISReport

Result of talis_check: rows (one TaLISRow per beam, rule and component), the settings used (thresholds, error set, tolerance interpretation) and notes on checks that were not evaluated. See violations, write_talis_csv.

TaLISRow

One check of talis_check: a (beam, rule, component) triple.

• beam — beam name ("upper beams"/"lower beams" for :tas_stay_in)
• rule — :capture_3w, :incidence_3w, :clearance_3w, :clearance_1w, :management_1w, :diagnostic_1w or :tas_stay_in (see talis_check)
• component — target component (:none when a beam misses every capture surface)
• status — :pass; :fail (the criterion is violated in the worst case); or :review (a TaLIS "evaluate further" outcome, or not decidable automatically)
• margin — worst-case value less the requirement, in unit (:mm, or :deg for angle rules); positive passes
• worst, nominal — the measured quantity in the worst case (errors and the tolerance applied) and at nominal (neither applied)
• required — the TaLIS threshold, in unit
• point — worst location (mm)
• note — consequence or explanation

talis_check(target, beams; capture, hardware = all surfaces, omega1_components = all
            surfaces, diagnostics = (), tolerance = 0.5, pivot = :tcc,
            pointing = 0.05, target_offset = 0.025, hardware_tolerance = 0.0,
            focus = 1.0, ssd = 0.0, offsets = nothing, open_ports = :nif,
            curvature = Dict(), level = 2, edge_step = 0.02, ...) -> TaLISReport

NIF TaLIS target-configuration checks from the "TCC Configuration Requirements" (NIF User Forum, 27 Oct 2018, LMF Shot RI Resources). Every distance is measured orthogonal to the beam, as the document states, and judged on the worst case over the error set and the rule tolerance, never at nominal.

capture lists the components beams are meant to land on (backlighter foils, capture surfaces, a hohlraum wall). Each beam's landing component is the first of them its nominal axis meets.

Rules

• :capture_3w — the capture_contour (10 %)-of-peak contour must lie ≥ capture_margin (0.5 mm) inside the landing component's substrate edge: the minimum over the edge of the transverse distance to the beam envelope (best-focus contour grown by the f-cone at each point's axial position, see BeamEnvelope). Substrate edges are the free edges of the opaque mesh (edges with a single triangle; edges shared with another component are not edges), sampled every edge_step mm. A beam whose axis misses every capture component fails with component :none.
• :incidence_3w — incidence < max_incidence (70°) to the target normal, the maximum over the landing component's surface inside the worst-case 10 % footprint (visible from the beam; exact normals on SphereSurface/CylinderSurface components), plus the tolerance angle (a component tilted by the tolerance changes incidence by up to as much).
• :clearance_3w — the clearance_contour (1 %)-of-peak contour must clear each hardware component other than the landing component by > clearance_margin (0.5 mm); hardware downstream of the landing point is skipped, and everything along the beam is checked if the beam lands on no capture component. Capture and clearance failures carry the TaLIS consequence: blow-by assessment by the backscatter working group.
• :clearance_1w — the 10 % contour of the 1ω footprint must clear each omega1_components component by > omega1_margin (0.2 mm). Not clearing is a :review (TaLIS: evaluate unconverted-light management), decided by the next rule.
• :management_1w — for each surface the 1ω footprint does not clear: pass if its radius of curvature is < cylinder_radius (2 mm, cylindrical) or < sphere_radius (5 mm, spherical); otherwise the specular 1ω reflection from every uncleared facet must stay > reflection_angle (20°) from every open quad (open_ports), less twice the tolerance angle (a tilt by α turns a reflection by 2α). Curvature comes from curvature[name] — (:cylinder, r), (:sphere, r), :flat, or (:dimpled, r) / (:dimpled, r, half_side) for a surface covered with spherical dimples of radius of curvature r (e.g. the dimpled 1ω "sombrero" shield around an ignition hohlraum's LEH, modeled as a flat annulus_mesh), judged like a sphere against sphere_radius; with half_side, a dimple half-side/radius below 0.25 (NIF User Guide §5.6.2) makes it a :review — else from the component's CylinderSurface/SphereSurface, or a planar mesh. For other meshes the curvature is unknown and a failing reflection check is a :review. A flat component without a curvature entry gets the reflection check, which a horizontal plate usually fails (it mirrors each beam into the conjugate port of the same hemisphere).
• :diagnostic_1w — the diagnostics components (diagnostic hardware modeled in the target) must stay ≥ 10 mm from 1ω light at TCC, growing linearly to 25 mm at 1 m (10 + 0.015 r mm, r the distance from TCC; interpretation of "a cone of 10 mm at TCC extruded to 25 mm at 1 m").
• :tas_stay_in — (NIF beams) no component may extend more than stay_in (19 mm) above the lowest aim point of an upper beam or below the highest aim point of a lower beam (TAS alignment stay-in zone; violating it may require a different alignment sequence or beam selection). hardware_tolerance is added to the extent.

The remaining requirements of the document are listed in TALIS_OUT_OF_SCOPE.

1ω footprint

The 1ω rules apply to beams whose quad is a NIF quad name (or that have an offsets entry). A NIF quad-level beam (port within 0.1° of its quad port, as from nif_quads) is expanded into its four beamlets (LMF beam table) sharing its aim and defocus. Each beamlet's 1ω footprint at its 3ω best-focus plane is a square of side omega1_size whose nearest edge is omega1_edge = 4.45 mm (TaLIS: the 10 % contour) from the 3ω axis, displaced along the beamlet's own side of its quad in φ̂ (the side of the quad axis its port lies on; NIF User Guide Fig. 4-12 — derived, confidence medium). The default side is the User Guide's 22 mm footprint grown by 4.8 − 4.45 = 0.35 mm per side, so its near edge is the TaLIS 10 % contour (22.7 mm). Away from that plane the footprint is the cone converging to the 1ω focus omega1_focus (default 460 mm, from nif_unconverted) beyond the 3ω focus, with its centre on the chief ray from the lens centre lens_distance (7.7 m) upstream: at axial position s the near edge is 4.45 + 0.027 s mm, i.e. closer to the 3ω axis upstream of focus (derived). Pass omega1_focus = Inf, lens_distance = Inf for a prism (the footprint fixed in the transverse plane). offsets maps beam names to a footprint direction (degrees from the port's θ̂ toward φ̂, or a vector) and overrides the NIF convention for that beam. The focus error moves the footprint with the 3ω focal plane; shadowing is ignored (conservative).

Tolerance and error set

The document adds "up to 0.5 degrees metrology/alignment/positioning tolerance" to the 3ω and 1ω clearances without saying how an angle becomes a distance. This interpretation is an assumption that the user must confirm with TaLIS. By default (pivot = :tcc) it is a lateral allowance r·tan(tolerance), with r the distance of the hardware point from TCC: the transverse displacement of the point when the target assembly rotates by the tolerance about TCC. Alternatives: pivot = :aim (rotation about the beam's aim point, so the allowance vanishes where the beam lands), :max (the larger of the two, most conservative), or a point (e.g. the mount of the component, pivot = (0, 0, 12.0)); tolerance = 0 drops it.

It is combined with the error set of clearance by linear addition (no RSS):

worst = nominal − (pointing + target_offset + hardware_tolerance) − focus/(2F) − r·tan(tolerance)

evaluated point by point and minimised over the component (for the 1ω footprint the focus term is the footprint shift over ±focus instead of the f-cone). The target_offset and hardware_tolerance partly overlap what the tolerance is meant to cover, so this double counts conservatively; set them to 0 to rely on the tolerance alone. ssd (mm) widens the 3ω envelopes as in clearance.

Hardware is sampled at triangle vertices and 4^level sub-triangles; substrate edges every edge_step mm. Clearance-only far-field wings (nif_wings) are not used: the TaLIS rules refer to contours of the beam spot.

talis_requirement(rule, settings) -> String

Human-readable requirement of a talis_check rule (:capture_3w, :incidence_3w, :clearance_3w, :clearance_1w, :management_1w, :diagnostic_1w, :tas_stay_in) under the thresholds in settings (a TaLISReport's settings).

violations(report::TaLISReport; status = (:fail, :review)) -> Vector{TaLISRow}

Rows of a TaLIS report whose status is in status; failures first, then by margin.

write_talis_csv(path, report)

Write every row of a TaLIS report as CSV (margins in the row's unit).