{% extends "base.html" %} {% block title %}Web UI Documentation{% endblock %} {% block body %}

Web UI Documentation

Everything you need to create gratings, run simulations, and plot results inside Grax Web.

Back to home Create grating

The active workspace root is {{ workspace_root }}. By default, Grax Web stores data in .grax-web/ in the current working directory unless you switch the workspace from the home page.

Storage Materials Gratings Simulations Parameter energy scans Multilayer design Plane mirror Plots Export Modify later

Where data is saved

Grax Web keeps all local state under the active workspace directory. The default workspace is .grax-web/ next to where you launch grax-web.

saved_gratings/One JSON file per saved grating spec.
runs/One run directory per simulation, with manifests and CSV outputs.
plots/Saved comparison plots and their manifests.
previews/Temporary and live preview images shown in the browser.

The workspace can be changed from the home page. When you switch workspaces, the app reads and writes future gratings, runs, and plots in the new location.

Materials

The grating form uses the same packaged Henke material list that the Python API uses. Pick a material from the dropdown. The density field is prefilled with the built-in default for that element, and you can type a measured density when your sample is a film, porous layer, or otherwise not bulk-like.

xrt-style material objects still work for compatibility during the transition, but Grax will warn that this path is deprecated and will be removed in a future release. For new work, prefer the string material name plus an optional density override.

Create and save gratings

  1. Open New grating from the top bar or the home page.
  2. Choose the grating type, period, numerical resolutions, and profile-specific parameters.
  3. Select the coating stack type and pick materials from the built-in material catalog.
  4. Use the live preview panel to confirm the shape before saving.
  5. Save the grating to store it in saved_gratings/<grating-id>.json.

After saving, the grating detail page lets you edit the profile, review the preview image, or delete the grating. Saved gratings are the starting point for simulations. The saved JSON now stores each material as a name plus density pair so the same sample can be reconstructed later.

Run simulations

  1. Open a saved grating from the home page.
  2. Pick Energy sweep, Angle sweep, Monochromator, Multilayer theta search, Parameter study, or Custom grid.
  3. Enter the energy range, diffraction order, Fourier orders, polarization (s is TE, p is TM), and any workflow-specific values.
  4. Pick the solver. RCWA is the default modal solver, inspired by RETICOLO. Nevière is the differential method. Both paths share the same grating and workflow inputs but propagate through the grating differently; the saved run records which one produced it. Nevière stays stable on gratings far deeper than modal RCWA can handle.
  5. Add an optional run comment if you want the saved run to carry a note or experiment tag.
  6. Choose the worker mode if you want auto or manual multiprocessing.
  7. Run the sweep and follow the progress page while the simulation writes results.

Each run gets its own directory under runs/<run-id>/. The manifest records the workflow, grating metadata, selected orders, comment, and progress state. The run directory also stores the result CSV files and generated preview images for that run.

Energy and angle scans

Energy sweep scans photon energy while keeping grazing incidence angle fixed. Angle sweep scans grazing angle at one selected energy. Monochromator scans energy at constant CFF and solves incidence geometry at every energy using the line density of the current grating combination.

Energy sweep and Angle sweep support independent parameters and coupled parameter rows. Two duty cycles and two coating materials produce four scan sets. Each set covers the full energy or angle range for its workflow. Monochromator scans the energy range for every configured variation combination. Coupling depth to duty cycle pairs the values row by row; it does not form another Cartesian axis. Parameters omitted from the variations keep their saved or shared simulation values.

The run page updates a live plot as points finish. Parameter combinations appear as separate curves; Angle sweep uses grazing angle on the horizontal axis, while Energy sweep and Monochromator use energy. The plot remains available after completion or abort.

Numerical ranges show both a point count and a step size. Edit either field to update the other. A requested step is adjusted to the nearest point count that includes both bounds: 100–110 eV with a requested step of 3 eV becomes four points at 3⅓ eV spacing. A single-point range has equal bounds and zero spacing. Integer ranges still show the actual rounded values. A coupled range keeps the source row count; editing its step changes the dependent endpoint.

One grouped run stores every combination, its resolved grating snapshot, and the selected energy or angle grid. Manage grating runs expands into per-scan settings and progress. An interrupted run can resume its unfinished points from its checkpoints.

Export scan tables downloads a ZIP of CSV and/or tab-separated DAT files plus YAML metadata. Each table fixes the other parameter axes and contains energy, or grazing angle for an Angle sweep, in the first column, followed by the efficiencies for each value of the selected axis. Missing values are NaN. For duty cycle × coating material, selecting both axes exports a duty-cycle table for each material and a material table for each duty cycle. The existing complete result export remains available.

When adding a grouped run to Plots, select its individual scans as well as diffraction orders. The saved plot preserves each scan's identity and styling. The older Custom grid workflow and its saved data remain available.

Geometry sketches

Grating and plane-mirror pages include a schematic side-on view with switchable Beams, Angles, and Lengths indicators. The drawing follows editable fields, highlights the focused dimension, and keeps actual numerical values in labels; geometry is intentionally schematic rather than to scale.

Multilayer grating design

The Multilayer design tab sizes a periodic multilayer coating for a blazed grating in two steps that share one configuration. The incident angle is not an input: every cell gets its own theta search, and the angle that search settles on is what the efficiency is reported at.

  1. Survey. Scans a d-spacing × blaze-angle grid, running one single-energy multilayer theta search per cell. It produces three plots: optimal blaze angle vs d-spacing, max efficiency vs d-spacing, and the full (d, blaze) efficiency heatmap with the optimal-blaze ridge overlaid.
  2. Energy scan. Sweeps the designs you pick over an energy range. Choose Scan best (the survey's single highest-efficiency cell), Scan all d (the optimal blaze at every d-spacing), or Choose manually to build a list of (d, blaze) cases from dropdowns. Two or more designs also get an overlay comparison plot.

Tick scan the best design over energy automatically when creating the study to chain step 2 straight off the survey — the plots render as soon as the survey lands and the scan starts underneath them. Either stage runs in the background with a live progress bar and can be aborted at any point — aborting stops the running solves immediately and offers to keep or discard the partial results; what was kept is resumed on the next run. Edit parameters on a study reopens the same form with its stored values: saving a change that a finished stage depended on marks that stage stale rather than deleting anything. Download script writes the study out as a single standalone Python file -- the parameters as named constants, then both stages behind --survey / --energy-scan flags (plus --best, --pairs and --eval) -- to run on a cluster or another machine with only grax installed. Re-running the survey marks a finished energy scan stale without deleting it.

multilayer_designs/<id>/study.jsonConfig and per-stage status.
survey/survey.csvOne row per surveyed cell.
survey/runs/d<d>nm/blaze<b>deg/Each theta search's full output.
plots/Headline survey plots and the titled energy-scan plots.
energy_scan/Per-design sweep artifacts.

Plane mirror

The Plane mirror tab computes the specular reflectivity of a single layer, a periodic multilayer or a custom list of any number of layers (add, remove and reorder rows; an empty roughness uses the default) on a flat substrate with the Parratt recursion. It is stateless and instant: the curve updates as you edit the form, and Download CSV saves the current curve. Choose an energy scan at a fixed grazing angle, an angle scan at a fixed energy, or a map of reflectivity versus angle and energy, the polarization (s, p or average) and a default interface roughness; per-layer roughness fields override it.

Saving. Give the mirror a name (and an optional label) and use Save plane mirror to keep the stack together with the current scan. On a saved mirror, Save scan attaches the current scan settings under a scan name and label (saving under an existing name overwrites it), Update mirror stores a changed stack, name or label, and each scan can be renamed, relabelled or deleted. The Plane mirrors page lists all saved mirrors and deletes several at once. Saved mirrors live in saved_plane_mirrors/ in the workspace.

Lateral grading varies every layer thickness along the mirror by a scale factor (linear in %/mm, or polynomial coefficients c0, c1, c2… in the position in mm from the mirror centre). The plot then shows the ungraded central curve and the average over sample points along the illuminated footprint length, which is broader and lower because each position reflects a different Bragg energy.

Compare and plot runs

  1. Open Plots from the top bar.
  2. Select one or more saved runs.
  3. Choose the diffraction orders you want to compare.
  4. Use the live Plotly preview to inspect the combined plot before saving it.
  5. Adjust the line color, marker type, marker size, and x/y axis scales directly in the form.
  6. Save the plot to create a dedicated entry under plots/<plot-id>/.

The saved plot page reopens the same interactive Plotly figure together with the selected runs and orders, so the comparison styling and the axis modes persist with the saved plot.

Export plots and manage saved data

How to modify the interface later

If you want to change the Web UI, these files control the main moving parts:

To change the default workspace folder, edit the create_app() setup in src/grax/web/app.py. To change the docs itself, edit this template and the matching external docs notes in docs/index.md and docs/installation/web-ui.md.

{% endblock %}