Using ModeForge

Pick a preset on the left (e.g. thick-lens focus), then change beam and component values — everything recomputes instantly. The plot shows the 1/e² envelope along z; on the right you get the output waist, pulse numbers and each component's aperture margin. The amber/red notes at the bottom are not decoration: ModeForge tells you honestly when something clips or an approximation reaches its limit.

Source: Gaussian (w0, z0, M²), elliptical/astigmatic (separate x/y) or a moment beam (D4σ + M²). The mode helper converts HG/LG orders into an envelope M² ("Apply as beam M²"). Pulse: energy or average power + rate plus FWHM duration and shape — peak power, fluence and intensity at the exit plane appear on the right. Components: add via the + buttons, click to select and edit, reorder with ←/→. Position z adjusts the preceding free space. The computation is paraxial ABCD matrix optics — exact within that approximation, no aberrations.

Two-lens grid search: define lens candidates (f, aperture) and position grids, set a target (radius at plane z or a target waist), choose constraints such as minimum separation and aperture margin. The result list shows the mismatch and optionally the sensitivity to position/focal/M² errors — "Send to beamline" installs a solution directly.

Load Zemax sequential files via LOAD FILE, drag & drop or paste (UTF-16 exports are detected), set λ for the refractive index, parse. Object/image planes of real exports are trimmed automatically. Simple singlets become a thick lens; more complex prescriptions (cemented doublets, multi-element) become a surface stack in the beamline — glass-glass interfaces included. Why is my import blocked? Unknown glasses (load and adopt an AGF catalog first), aspheres/mirrors/tilts (CONI, XDAT, GLAS MIRROR …), unknown lens units, or indices outside the Sellmeier validity range. That is deliberate: an honest no beats a wrong lens.

Propagates the scalar field through the actual beamline and reads it out at a freely chosen probe plane. Grid N and dx set resolution and extent — AUTO dx is the right starting point. Field source: Gaussian or true HG/LG modes (m,n or p,l) — the waist is read as the measured second-moment waist; set the beam M² to match for a consistent cross-check (a note reminds you). Surface phase: "Ideal" = paraxial phase mask; "Real sag (TEA)" imprints the exact spherical surface phase — sag-driven spherical aberration becomes visible. Reading results: the cross-check compares the field against the paraxial envelope. Blue = deviation expected from diffraction (hard aperture). Amber "SAMPLING LIMIT" = the grid cannot resolve the result (e.g. a focus smaller than one grid cell) — the deviation is then a grid artifact, not physics. The warning states the N you would need.

Paste caustic measurements as CSV: one row per point z_mm, width, pick the width basis (1/e² radius, FWHM/D4σ diameter, rms). The least-squares fit returns w0, z0, M² and residuals; "Use as beam" makes the fit your project source.

Load a file: in the Analyzer tab (pill: IMG), drop or pick a .tif/.tiff/.png file (up to 128 MB, decoded images capped at 4096 × 4096 px). Multi-page TIFF and multi-channel PNG add page/channel pickers; set the physical pixel pitch (µm/px, x and y) to see physical widths alongside pixel widths. Background: today's choices are None or a manual offset in counts; either way the analyzer estimates a noise scale sigma_B — from your background reference rectangles if you gave any, otherwise from a thin rim frame around the ROI. Negative values after correction are never clipped — a systematic negative bias is exactly what the warnings below are watching for. ROI: Full frame, a rectangle dragged on the image (drag inside to move, drag an edge or corner to resize), typed pixel coordinates (x0, y0, width, height), or the dashed suggested ROI with "Apply suggestion". Whichever is set when you click "Run analysis" becomes the confirmed ROI — the fixed domain every release gate and both moment stages read for that run. Reading the preview: a compact spot is framed at about 3× the D4sigma diameter; switch the view to full frame to see the blue ROI rectangle on the whole sensor. The solid green overlay is the released D4sigma ellipse; the dashed orange overlay is the fit-width ellipse — never the ROI. A 4sigma ellipse encloses about 86 percent of a Gaussian's power, so the display stretch still shows fainter tails outside it. Three numbers, on purpose: the headline tile is D4σ (ellipse) — a diameter measured inside an aperture fitted to the beam; it is the analyzer's most trustworthy released number. Next to it, fit width 4sigma is the width the Gaussian model itself predicts — sharper on clean beams, but a model number, not a measurement. The Moments/Profiles panel additionally shows the raw ROI moments — worth looking at, never released as the headline value. Suppressed? When D4σ (ellipse) cannot be trusted, the tile shows a reason instead of guessing: fit_not_converged (the model fit did not settle), nonpositive_amplitude (the fit found no real peak), residual_high (the fit does not match the data well enough, relative to the noise), aperture_clipped (the check aperture would reach outside your ROI), alpha_inconsistent (the shape is not consistent enough with a clean Gaussian core — wings, a second lobe, a flat top), multi_peak (more than one significant peak was found). None of these is a bug report — the analyzer is deliberately refusing to hand you a number it does not trust. Warnings worth reading: negative power flags a background correction that leaves too little (or unusually much) negative signal for a clean zero-mean background; ROI sensitive means the released width moves more than expected when the ROI is nudged; residual high and multi peak explain why a release was suppressed; pedestal hint warns of a flat residual offset biasing the width upward; width scatter reports how much the released width itself moves under this image's own noise and warns above 5 percent; absorbed power flags a faint wide wing beyond the aperture that would otherwise vanish into the background fit — though a weak enough wing at very low signal-to-noise can still slip past it; clipping suspect flags a plateau of pixels sitting below the file format's saturation limit, a possible sign of sensor clipping; hot-pixel, saturation and float-special warnings describe the raw file itself, before any of the analysis above runs. Every number here comes from the documented ModeForge analyzer method (see docs/theory in the repository).

The Caustic tab runs a campaign of camera frames at several z positions. Each plane becomes a second-moment observation, repeats are aggregated, and a fit gives w0, z0 and M² per axis. The result can be adopted as a measured source in the beamline.

The workflow in five steps

1. Pick campaign files: “Pick campaign files” loads a multipage TIFF z series or individual images, with one table row per frame. Confirm the OME-to-file mapping when asked. A z derived from nominal plane spacing in a file is a suggestion, not a measurement; check and confirm it before observing.
2. Confirm the camera statements: Before observing, review and confirm the four statements in “Camera & capture”. The section below explains what each confirms.
3. Observe frames: “Observe frames” measures each included frame: background, region of interest, second moments and plane status. The progress bar counts frames and estimates time left. Aborting keeps frames already observed; the remaining frames need another run.
4. Fit campaign: “Fit campaign” groups observed frames by group id into planes and fits w(z) for both axes with an uncertainty ensemble. Every included row needs a finite z and a group. The fit view shows planes with error bars, the fitted curve and 68 % / 95 % bands; a blocked axis shows points only.
5. Use as measured source: “Use as measured source” is possible when both axes are ready and the uncertainty is complete. If on review, confirm the review checkbox; a blocked result locks the handoff. The ensemble is then propagated through the beamline. The aperture table shows the margin and clipping risk at each plane.

Importing single images and naming files

• Pick or drop all campaign files in one pass. If every name has a readable z, files are sorted by z, then in natural name order for equal z. If any name has no readable z, all files are sorted naturally, so img2 comes before img10. Later passes are appended.
• A z marker followed by a number is read, for example z-12.5mm, z+3.0mm, z=3 or z_012p5; p represents the decimal point. The unit is mm unless cm, um or µm is specified. Without a marker, only a number with an explicit unit is read, such as -3.0mm or 250um.
• Image numbers, dates, values with other units such as 10m, values outside ±10,000 mm, and names with two different values are not read. Recommended names include the z marker and a repeat number, for example beam_z-12.5mm_rep01.tif and beam_z-12.5mm_rep02.tif.
• A z read from a file name appears as a grey suggestion marked “from file name, please check”. A file name is not a measurement: check each value, then confirm with “Adopt z from file names”. Nothing is observed with an unconfirmed suggestion. Multipage files without OME metadata get no suggestion.
• If names contain no z, use “Fill z sequence”: enter “Start z (mm)”, “Step (mm)” and “Frames per plane”, then use “Fill z of the included rows”. Start −2 mm, step 2 mm and 3 frames per plane produce −2, −2, −2, 0, 0, 0, 2, 2, 2, … Existing z values of included rows are overwritten, and each row remains editable. Rows are filled in the order the files were added; group ids set by hand stay as they are. If rows do not divide evenly, the last plane has fewer frames and a note explains this.
• Frames with the same z form one plane and their repeats are aggregated.

What the “Camera & capture” checkboxes confirm

• “Image axes match the laboratory axes (no swap, no mirroring)” confirms identity mapping. A swap or mirror would assign the fitted axes to the wrong laboratory directions. It is part of every observation; changing it discards observed frames.
• “The images are raw data without a display curve” confirms that pixel values are proportional to the amount of light. A display curve would distort the beam width. Changing this statement discards observed frames.
• “The sensor is linear and nowhere saturated” confirms linear response without saturation; otherwise the computed width is not valid. Until confirmed, every plane stays on review. Changing the statement discards observed frames.
• “Pixel sensitivity across the sensor” has three choices: “not checked”, “checked, deviation negligible” and “Pixel-sensitivity correction is already in the files”. Uneven sensitivity, such as vignetting or dust, shifts centroid and width. “not checked” keeps every plane on review; changing the choice discards observed frames.
• Without all four statements, the software cannot ensure that pixel values are proportional to intensity, so the result stays on review. “Use typical measurement camera” sets raw data, a linear sensor and negligible sensitivity spread. It does not set image axes and is not for webcams or JPEG with automatic gamma or strong uncorrected vignetting.

Reading status: ready, review, blocked

• Usable / ready results carry through. Review is usable but flagged. Blocked results are excluded.
• Hover or focus the status pill to read its reasons. The reasons summary jumps to the matching control for operator statements.
• “Override…” lifts a blocked plane to review with a written reason stored with that plane. The measurement data and checksum do not change.
• The review confirmation checkbox records that the listed reasons were seen and accepted, and enables handoff. A blocked result stays blocked.

Minimum amounts

• A fit needs at least 5 planes.
• Ready status needs at least 10 planes.
• The coupling test needs at least 6 planes with 6 repeats each.
• Back-calculation needs at least six distinct usable repeats per plane.

What a change discards

• Changing pixel pitch, image axes, camera statements, background method, page or z discards all observed frames; observe again.
• Changing wavelength or z reference discards fit products, including the ensemble and propagated envelope, but keeps observed frames. If z reference is empty, the last measurement plane is used.
• Changing a group discards only fit products. An empty group id is derived from z. Changing the page of a multipage file points the row at another frame and discards observations.
• Power enters neither fit nor checksum, so changing it discards nothing.

Bundle

“Export bundle” and “Import bundle” save and load observations, groups, fit, ensemble and the campaign table in a reproducible archive without pixel data. Two exports of the same state are byte-identical. After import, rows are marked as not loaded; pick the source files again before observing. Reopening a file replaces its earlier rows; pixels stay in the browser.

See also docs/guide/caustic.md and docs/theory/caustic.md.

When the beam is measured behind an optic that is removed again, this card calculates back to the source in front of that optic.

Choosing the setup

“Setup” offers “Directly measured” or “Measurement train (back-calculate to source)”. Directly measured uses the caustic at the camera as the source. Measurement train calculates back through the specified measurement optic and requires assumptions.

Describing the measurement train

• “Thin lens” needs focal length and clear aperture; “Optical file (ZMX)” takes the surfaces from a file.
• “Focal length f” enters the back-calculation directly; its uncertainty belongs to the geometry errors.
• “Clear aperture radius” is compared with the beam radius at the lens.
• “Source-to-optic distance L” is measured from the source to the optic entry. Together with the entry position, it fixes where the source sits in front of the optic.
• “Image-side entry position” uses the same z scale as the campaign table.
• Set “Uncertainty” for each value: “Fixed (no uncertainty)” assumes no error; “Normal (σ)”, “Rectangular (half-width)” and “Triangular (half-width)” describe uncertainty distributions. “Unknown” marks an unquantified source and keeps adoption on review or blocked.

Declaring assumptions: what the three statements confirm

1. “I declare the source model to be decoupled along the laboratory axes.” confirms no x–y coupling, twist or astigmatic rotation. Without the axis assumption the source cannot be adopted. A clearly significant cross term in the data still blocks adoption; otherwise the result remains on review because this is an assumption.
2. For “Additional geometry errors”, “mutually independent” draws the errors separately and lifts this block; adoption also needs the third statement below. “dependence unspecified” allows a diagnostic run only and keeps adoption blocked.
3. “I confirm that the additional geometry errors are independent of measurement error. The shared z calibration remains coupled.” confirms that optic-setup errors and camera-campaign errors do not share a cause, such as using the same ruler for both. Without confirmation, adoption is blocked; the shared z calibration is always treated as coupled.

Reading and releasing the result

• “At measurement plane” shows the beam at the measurement plane; “At the source (back-calculated)” shows the result in front of the measurement optic.
• When the result is on review, “I acknowledge the displayed assumptions and limitations for this source adoption.” records that the shown assumptions and limits were read and accepted. It enables adoption, but does not release a blocked result.
• An “Unknown” uncertainty can leave the result on review or blocked. The diagnosis lists reasons; too few repeats do not allow a reliable scatter estimate.

Adopting

• “Adopt back-calculated source” adopts the source in front of the measurement optic. “Use at measurement plane” uses the beam measured at the camera directly as the source, without back-calculating.
• The adopted source survives bundle export and import.
• “Declare assumptions again” unlocks the archived declarations. The earlier result does not change; new declarations lead to a new run.

What blocks adoption

• Too few repeats: “There are too few repeated frames to check the source model.” Back-calculation needs at least six distinct usable repeats per plane.
• An unestablished source model or a missing axis statement prevents adoption.
• A clearly significant cross term blocks adoption even when the axis statement is confirmed.
• “dependence unspecified” allows a diagnostic run only. Measurement-error independence must also be confirmed.
• An uncertainty marked “Unknown” leaves the result on review or blocked; a blocked axis or ensemble prevents handoff.

The coupling test

The coupling gate checks the cross moments of all planes jointly with an exact sign-flip test, and needs at least six planes and six repeats per plane. A compatible result does not prove decoupling; adoption still needs the explicit declaration of the uncoupled model. For delivered products that include jitter, it answers “undetermined” because that path is not calibrated yet.

• Paraxial: fast mode is ABCD optics — no aberrations, no large angles (high NA ≫ 0.1–0.2 is out of scope).
• TEA: "real sag" is a thin-element approximation: sag aberration yes, incidence-angle aberrations no.
• One wavelength per run: dispersion enters only via n(λ); compare chromatic behavior by switching λ.
• Grid: the field mode can only represent what N·dx holds and dx resolves — take the sampling warnings seriously.
• Not supported: aspheres, mirrors/folds, tilts/decenters, vector fields/polarization.
• No laser-safety proof: results are approximations for design and teaching, not a safety assessment.
• Analyzer noise: high noise widens the self-calibrated release ceiling — weak wing structure on a beam becomes statistically invisible around SNR 20.
• Analyzer satellites: a small second beam below roughly a quarter of the main peak is not reliably detectable at SNR 20.
• Analyzer width scatter: the released width now ships a per-image noise-scatter estimate and warns above 5 percent — a single frame does not pin the width tighter than that.
• Analyzer wings: a faint wide wing beyond the aperture is flagged by the absorbed-power probe; a weak enough wing at very low signal-to-noise can still slip past it.
• Sensor clipping: a plateau below the file format's saturation limit is now flagged as a possible sign of clipping.
• Analyzer determinism: results are deterministic per file — the same image with the same settings always releases the same numbers.
• The coupling gate currently judges only the intrinsic product.

"Export JSON" saves the whole project as a versioned, diffable file; "Import JSON" (also via file/drag & drop) loads it back. Ideal for version control, sharing and reproducibility.