{% extends "base.html" %}
{% block title %}Web UI Documentation{% endblock %}
{% block body %}
<section class="section-head">
  <div>
    <h1>Web UI Documentation</h1>
    <p>Everything you need to create gratings, run simulations, and plot results inside Grax Web.</p>
  </div>
  <div class="actions">
    <a class="button" href="{{ url_for('index') }}">Back to home</a>
    <a class="button primary" href="{{ url_for('new_grating') }}">Create grating</a>
  </div>
</section>

<section class="notice">
  <p>
    The active workspace root is <code>{{ workspace_root }}</code>. By default, Grax Web stores data in
    <code>.grax-web/</code> in the current working directory unless you switch the workspace from the home page.
  </p>
  <div class="docs-toc">
    <a class="button" href="#storage">Storage</a>
    <a class="button" href="#materials">Materials</a>
    <a class="button" href="#gratings">Gratings</a>
    <a class="button" href="#simulations">Simulations</a>
    <a class="button" href="#multilayer-design">Multilayer design</a>
    <a class="button" href="#plane-mirror">Plane mirror</a>
    <a class="button" href="#plots">Plots</a>
    <a class="button" href="#export">Export</a>
    <a class="button" href="#modify">Modify later</a>
  </div>
</section>

<section class="docs-section" id="storage">
  <h2>Where data is saved</h2>
  <p>
    Grax Web keeps all local state under the active workspace directory. The default workspace is
    <code>.grax-web/</code> next to where you launch <code>grax-web</code>.
  </p>
  <div class="list compact">
    <div class="row"><strong><code>saved_gratings/</code></strong><span>One JSON file per saved grating spec.</span></div>
    <div class="row"><strong><code>runs/</code></strong><span>One run directory per simulation, with manifests and CSV outputs.</span></div>
    <div class="row"><strong><code>plots/</code></strong><span>Saved comparison plots and their manifests.</span></div>
    <div class="row"><strong><code>previews/</code></strong><span>Temporary and live preview images shown in the browser.</span></div>
  </div>
  <p>
    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.
  </p>
</section>

<section class="docs-section" id="materials">
  <h2>Materials</h2>
  <p>
    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.
  </p>
  <p>
    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.
  </p>
</section>

<section class="docs-section" id="gratings">
  <h2>Create and save gratings</h2>
  <ol>
    <li>Open <strong>New grating</strong> from the top bar or the home page.</li>
    <li>Choose the grating type, period, numerical resolutions, and profile-specific parameters.</li>
    <li>Select the coating stack type and pick materials from the built-in material catalog.</li>
    <li>Use the live preview panel to confirm the shape before saving.</li>
    <li>Save the grating to store it in <code>saved_gratings/&lt;grating-id&gt;.json</code>.</li>
  </ol>
  <p>
    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.
  </p>
</section>

<section class="docs-section" id="simulations">
  <h2>Run simulations</h2>
  <ol>
    <li>Open a saved grating from the home page.</li>
    <li>Pick a workflow: fixed angle, monochromator, multilayer theta search, or parameter study.</li>
    <li>Enter the energy range, diffraction order, Fourier orders, polarization (<code>s</code> is TE, <code>p</code> is TM), and any workflow-specific values.</li>
    <li>
      Pick the solver. <strong>RCWA</strong> is the default modal solver, inspired
      by RETICOLO. <strong>Nevi&egrave;re</strong> 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&egrave;re
      stays stable on gratings far deeper than modal RCWA can handle.
    </li>
    <li>Add an optional run comment if you want the saved run to carry a note or experiment tag.</li>
    <li>Choose the worker mode if you want auto or manual multiprocessing.</li>
    <li>Run the sweep and follow the progress page while the simulation writes results.</li>
  </ol>
  <p>
    Each run gets its own directory under <code>runs/&lt;run-id&gt;/</code>. 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.
  </p>
</section>

<section class="docs-section" id="geometry-sketch">
  <h2>Geometry sketches</h2>
  <p>Grating and plane-mirror pages include a schematic side-on view with switchable <strong>Beams</strong>, <strong>Angles</strong>, and <strong>Lengths</strong> 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.</p>
</section>

<section class="docs-section" id="multilayer-design">
  <h2>Multilayer grating design</h2>
  <p>
    The <a href="{{ url_for('multilayer_design_index') }}">Multilayer design</a> 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.
  </p>
  <ol>
    <li>
      <strong>Survey.</strong> 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 <code>(d, blaze)</code> efficiency
      heatmap with the optimal-blaze ridge overlaid.
    </li>
    <li>
      <strong>Energy scan.</strong> Sweeps the designs you pick over an energy range. Choose
      <em>Scan best</em> (the survey's single highest-efficiency cell), <em>Scan all d</em>
      (the optimal blaze at every d-spacing), or <em>Choose manually</em> to build a list of
      <code>(d, blaze)</code> cases from dropdowns. Two or more designs also get an overlay
      comparison plot.
    </li>
  </ol>
  <p>
    Tick <em>scan the best design over energy automatically</em> 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. <em>Edit parameters</em>
    on a study reopens the same form with its stored values: saving a change that a finished stage
    depended on marks that stage <em>stale</em> rather than deleting anything.
    <em>Download script</em> writes the study out as a single standalone Python file -- the
    parameters as named constants, then both stages behind <code>--survey</code> /
    <code>--energy-scan</code> flags (plus <code>--best</code>, <code>--pairs</code> and
    <code>--eval</code>) -- to run on a cluster or another machine with only grax installed.
    Re-running
    the survey marks a finished energy scan <em>stale</em> without deleting it.
  </p>
  <div class="list compact">
    <div class="row"><strong><code>multilayer_designs/&lt;id&gt;/study.json</code></strong><span>Config and per-stage status.</span></div>
    <div class="row"><strong><code>survey/survey.csv</code></strong><span>One row per surveyed cell.</span></div>
    <div class="row"><strong><code>survey/runs/d&lt;d&gt;nm/blaze&lt;b&gt;deg/</code></strong><span>Each theta search's full output.</span></div>
    <div class="row"><strong><code>plots/</code></strong><span>Headline survey plots and the titled energy-scan plots.</span></div>
    <div class="row"><strong><code>energy_scan/</code></strong><span>Per-design sweep artifacts.</span></div>
  </div>
</section>

<section class="docs-section" id="plane-mirror">
  <h2>Plane mirror</h2>
  <p>
    The <a href="{{ url_for('plane_mirror_page') }}">Plane mirror</a> 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 <strong>Download CSV</strong>
    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.
  </p>
  <p>
    <strong>Saving.</strong> Give the mirror a name (and an optional label) and use <em>Save plane mirror</em>
    to keep the stack together with the current scan. On a saved mirror, <em>Save scan</em> attaches the
    current scan settings under a scan name and label (saving under an existing name overwrites it),
    <em>Update mirror</em> stores a changed stack, name or label, and each scan can be renamed, relabelled or
    deleted. The <a href="{{ url_for('plane_mirror_index') }}">Plane mirrors</a> page lists all saved mirrors
    and deletes several at once. Saved mirrors live in <code>saved_plane_mirrors/</code> in the workspace.
  </p>
  <p>
    <strong>Lateral grading</strong> varies every layer thickness along the mirror by a scale factor
    (linear in %/mm, or polynomial coefficients c0, c1, c2&hellip; 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.
  </p>
</section>

<section class="docs-section" id="plots">
  <h2>Compare and plot runs</h2>
  <ol>
    <li>Open <strong>Plots</strong> from the top bar.</li>
    <li>Select one or more saved runs.</li>
    <li>Choose the diffraction orders you want to compare.</li>
    <li>Use the live Plotly preview to inspect the combined plot before saving it.</li>
    <li>Adjust the line color, marker type, marker size, and x/y axis scales directly in the form.</li>
    <li>Save the plot to create a dedicated entry under <code>plots/&lt;plot-id&gt;/</code>.</li>
  </ol>
  <p>
    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.
  </p>
</section>

<section class="docs-section" id="export">
  <h2>Export plots and manage saved data</h2>
  <ul>
    <li>Use <strong>Save plot</strong> in the plot builder to store the interactive compare view in <code>plots/</code>.</li>
    <li>Use <strong>Manage runs</strong> to rename saved runs, edit their comments, or delete them.</li>
    <li>Use <strong>Manage gratings</strong> to inspect, edit, or delete saved grating definitions.</li>
    <li>Use the workspace switcher on the home page if you want the app to read and write a different local folder.</li>
  </ul>
</section>

<section class="docs-section" id="modify">
  <h2>How to modify the interface later</h2>
  <p>If you want to change the Web UI, these files control the main moving parts:</p>
  <ul>
    <li><code>src/grax/web/app.py</code>: routes, workspace behavior, simulation wiring, and runtime page data.</li>
    <li><code>src/grax/web/templates/*.html</code>: page text, layout, and button placement.</li>
    <li><code>src/grax/web/static/web.css</code>: styling and responsive layout.</li>
    <li><code>src/grax/web/static/web.js</code>: client-side preview, Plotly rendering, and form interactions.</li>
    <li><code>src/grax/web/persistence.py</code>: how gratings are stored and reconstructed from JSON.</li>
    <li><code>src/grax/web/runs.py</code>: run manifests, result loading, and comparison plot saving.</li>
  </ul>
  <p>
    To change the default workspace folder, edit the <code>create_app()</code> setup in
    <code>src/grax/web/app.py</code>. To change the docs itself, edit this template and the matching external docs
    notes in <code>docs/index.md</code> and <code>docs/installation/web-ui.md</code>.
  </p>
</section>
{% endblock %}