From 0a86f85231072047b65fb2b3fe857441c66b3bc4 Mon Sep 17 00:00:00 2001 From: salman Date: Mon, 16 Nov 2026 10:32:05 +0100 Subject: [PATCH] Add Sphinx user manual (docs/) Create a Sphinx-based manual similar to muSRFlow's: conf reads version from package.json, RTD theme, HTML/PDF targets, and chapters covering overview, getting started, Windows/Linux install, layers/projectile, scans, results, advanced parameters, sharing, web deployment, troubleshooting, and glossary. Build output (_build/) is gitignored. Builds cleanly with 'make -C docs html'. --- docs/.gitignore | 1 + docs/Makefile | 15 +++++++ docs/make.bat | 35 +++++++++++++++ docs/source/_static/.gitkeep | 0 docs/source/advanced.rst | 14 ++++++ docs/source/conf.py | 63 +++++++++++++++++++++++++++ docs/source/getting-started.rst | 29 +++++++++++++ docs/source/glossary.rst | 15 +++++++ docs/source/index.rst | 34 +++++++++++++++ docs/source/install-linux.rst | 63 +++++++++++++++++++++++++++ docs/source/install-windows.rst | 71 +++++++++++++++++++++++++++++++ docs/source/layers-projectile.rst | 21 +++++++++ docs/source/overview.rst | 23 ++++++++++ docs/source/results.rst | 12 ++++++ docs/source/scans.rst | 9 ++++ docs/source/sharing.rst | 10 +++++ docs/source/troubleshooting.rst | 24 +++++++++++ docs/source/web-deployment.rst | 11 +++++ 18 files changed, 450 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_static/.gitkeep create mode 100644 docs/source/advanced.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/getting-started.rst create mode 100644 docs/source/glossary.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/install-linux.rst create mode 100644 docs/source/install-windows.rst create mode 100644 docs/source/layers-projectile.rst create mode 100644 docs/source/overview.rst create mode 100644 docs/source/results.rst create mode 100644 docs/source/scans.rst create mode 100644 docs/source/sharing.rst create mode 100644 docs/source/troubleshooting.rst create mode 100644 docs/source/web-deployment.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..ba65b13 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..1f18e0f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,15 @@ +# Minimal makefile for Sphinx documentation +# + +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..b344c6a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst new file mode 100644 index 0000000..2dd7f53 --- /dev/null +++ b/docs/source/advanced.rst @@ -0,0 +1,14 @@ +Advanced transport parameters +=========================== + +The **Advanced** tab exposes collision/recoil and model choices (e.g. +interaction potential and electronic stopping parameterizations) used by +TRIM.SP-NL. Hover over parameter names for tooltips. + +Leave defaults unchanged unless you have a specific reason; note that some +options apply only to certain projectile/energy ranges (see the in-app help +text). + +The **Reference & citation** panel lists the underlying TRIM.SP literature +and the recommended citation for published work. The in-app help also points +to current stopping-power coefficient references for the relevant options. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..1ab690b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,63 @@ +# Configuration file for the Sphinx documentation builder. + +import json +import os +import sys + + +source_dir = os.path.dirname(os.path.abspath(__file__)) +repo_root = os.path.abspath(os.path.join(source_dir, "..", "..")) +if repo_root not in sys.path: + sys.path.insert(0, repo_root) + + +def load_version(): + try: + with open(os.path.join(repo_root, "package.json"), "r", encoding="utf-8") as handle: + package = json.load(handle) + version = str(package.get("version", "0.0.0")) + except Exception: + version = "0.0.0" + return version, version + + +version, release = load_version() + +project = "TRIMSP-NL Workbench" +copyright = "2026 Zaher Salman" +author = "Zaher Salman" + +extensions = [] +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +master_doc = "index" +root_doc = "index" + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_title = project + " User Manual" +html_theme_options = { + "navigation_depth": 3, + "titles_only": False, +} + +latex_engine = "xelatex" +latex_use_xindy = False +latex_elements = { + "classoptions": ",12pt", + "papersize": "a4paper", + "pointsize": "12pt", + "sphinxsetup": "hmargin={2cm,2cm}, vmargin={2cm,3cm}", + "fncychap": r"\usepackage[Sonny]{fncychap}", +} +latex_documents = [ + ( + master_doc, + "trimsp.tex", + project + " User Manual", + author, + "manual", + False, + ), +] diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst new file mode 100644 index 0000000..2bbb196 --- /dev/null +++ b/docs/source/getting-started.rst @@ -0,0 +1,29 @@ +Getting started +=============== + +Quick Start help +---------------- + +Click the **?** button in the toolbar to open the contextual Quick Start panel. +The share button copies a link encoding the current scientific setup (layers, +projectile, scan, RNG, advanced settings); it does **not** include local paths, +file prefixes, worker counts, or results. + +Desktop (Windows) +----------------- + +Follow :doc:`install-windows`. After the first launch, the app imports the +bundled WSL2 engine runtime automatically. + +Desktop (Linux) +--------------- + +Follow :doc:`install-linux`. RPM, DEB, and Flatpak packages include the +static ``trimspNL`` engine. + +Web +--- + +Open the TRIMSP-NL web URL provided by your site administrator. Set a project +prefix and work through the same tabs; use **Outputs** and **Details** in the +status bar for results and logs after a run. diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst new file mode 100644 index 0000000..5666f3e --- /dev/null +++ b/docs/source/glossary.rst @@ -0,0 +1,15 @@ +Glossary +======== + +**TRIM.SP-NL** + The generalized multilayer Fortran transport engine. + +**TRIMSP-NL Workbench** + The engine plus the GUI and scan-management workflow. + +**Work folder** + Local directory where inputs/outputs are written (desktop) or staged for a + web run as configured by the server. + +**Scan** + Repeated simulations over a range or list of a chosen parameter. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..be7d2b7 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,34 @@ +TRIMSP-NL Workbench User Manual +================================ + +TRIMSP-NL Workbench is a graphical workflow for low-energy muon and ion +implantation simulations. It combines the **TRIM.SP-NL** Fortran transport +engine with a desktop (Electron) and web interface for preparing layered +targets, running single shots or parameter scans, and plotting implantation +profiles and layer fractions. + +Start with :doc:`install-windows` or :doc:`install-linux` for desktop setup. +For the browser edition and server deployment, see :doc:`web-deployment`. + +These pages describe the end-user workflow, organised around the main window +tabs and mirroring the in-app Quick Start help (the ``?`` button). + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + overview + getting-started + install-windows + install-linux + layers-projectile + scans + results + advanced + sharing + web-deployment + troubleshooting + glossary + +If anything in this manual does not match the behaviour you see, contact +`Zaher Salman `_. diff --git a/docs/source/install-linux.rst b/docs/source/install-linux.rst new file mode 100644 index 0000000..5463bc5 --- /dev/null +++ b/docs/source/install-linux.rst @@ -0,0 +1,63 @@ +.. _linux-installation: + +Linux installation +================== + +Linux packages (RPM, DEB, Flatpak) bundle the statically linked ``trimspNL`` +engine. Node.js and npm are not needed on the target PC. Replace ```` +with the package version you obtained. + +Install from a package +---------------------- + +RPM +~~~ + +.. code-block:: bash + + sudo dnf install ./trimsp--1.x86_64.rpm + trimsp + +DEB +~~~ + +.. code-block:: bash + + sudo apt install ./trimsp__amd64.deb + trimsp + +Flatpak +~~~~~~~ + +.. code-block:: bash + + flatpak install --user ./ch.psi.lem.TrimSP_stable_x86_64.flatpak + flatpak run ch.psi.lem.TrimSP + +Running from source +------------------- + +Requires Node.js/npm and the Fortran toolchain (``gfortran``, ``make``): + +.. code-block:: bash + + cd trimsp + npm install + npm start + +Build engines: + +.. code-block:: bash + + npm run build:fortran # static -> resources/bin/trimspNL + npm run build:fortran:dynamic # dynamic -> resources/bin/trimspNL + +Building packages +----------------- + +.. code-block:: bash + + npm ci + npm run make # deb + rpm + npm run make:flatpak + npm run checksums diff --git a/docs/source/install-windows.rst b/docs/source/install-windows.rst new file mode 100644 index 0000000..b2958bf --- /dev/null +++ b/docs/source/install-windows.rst @@ -0,0 +1,71 @@ +.. _windows-installation: + +Windows installation +==================== + +The Windows installer (``TRIMSP-NL-Workbench-Setup.exe``) includes the +application and the ``trimspNL`` engine. Windows cannot run the Linux engine +natively, so the engine runs inside a bundled **WSL2** distribution prepared +on first launch. Node.js, npm, or a separate engine installation are not +required. + +Before you start +---------------- + +* **64-bit Intel/AMD PC** (x64). +* **WSL2** installed and updated (Windows 11 recommended). +* Administrator access once to enable WSL/virtualization features. +* Obtain the installer from the project release (see the repository README). + The installer is unsigned; Windows may show standard publisher warnings. + +Install step by step +-------------------- + +1. **Install WSL** (skip if already installed). In **PowerShell as + Administrator**: + + .. code-block:: powershell + + wsl --install --no-distribution + + Restart Windows. Ubuntu is not required. + +2. **Update and check WSL**: + + .. code-block:: powershell + + wsl --update + wsl --version + +3. **Install TRIMSP-NL Workbench** by running ``TRIMSP-NL-Workbench-Setup.exe``. + Do not extract or import the bundled runtime manually. + +4. **Launch the app** (normal user). On first launch it imports the runtime as + ``trimspNL-runtime`` into ``%LOCALAPPDATA%\TrimSP\trimspNL-runtime``. The + status bar shows progress; the first simulation waits for import. Verify: + + .. code-block:: powershell + + wsl --list --verbose + + ``trimspNL-runtime`` should appear with **VERSION 2**. + +5. **Choose a work folder and run**. Set a writable **Work Folder** on a + Windows drive (e.g. ``C:\Users\\TrimSP\work``). Paths are translated + for WSL automatically. Confirm outputs (e.g. ``*_E*.rge``, + ``_Seq_Results.dat``) appear in the folder. + +Updating +-------- + +Install the new application over the previous one. An existing imported +``trimspNL-runtime`` distribution is preserved; keep work folders outside the +install directory. + +Troubleshooting +--------------- + +* Ensure virtualization is enabled and WSL is healthy (``wsl --status``). +* Confirm the engine inside the distro: + ``wsl -d trimspNL-runtime -- /opt/trimsp-runtime/bin/trimspNL``. +* Engine runs are console-only; file dialogs follow normal Windows behavior. diff --git a/docs/source/layers-projectile.rst b/docs/source/layers-projectile.rst new file mode 100644 index 0000000..7ea7e99 --- /dev/null +++ b/docs/source/layers-projectile.rst @@ -0,0 +1,21 @@ +Layers and projectile +====================== + +Layers tab +---------- + +In the **Layers** tab: + +1. Set the **output folder** and **file prefix**. +2. Choose the number of **layers**. +3. For each layer enter composition, density, and thickness. Known material + densities may be filled automatically; a highlighted estimate should be + verified before running. + +Projectile +---------- + +Set the projectile species, incident **energy**, **angle**, energy/angle +**spread** (as applicable), random-number generator, and **seed**. + +Refer to the tooltips in the UI for field-specific guidance. diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..65078dd --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,23 @@ +Overview +======== + +TRIMSP-NL Workbench has two main components: + +* **TRIM.SP-NL** — the generalized multilayer Fortran Monte Carlo transport + engine. +* **TRIMSP-NL Workbench** — the graphical user interface, scan management, and + plotting workflow (desktop Electron app or browser interface). + +Typical workflow +---------------- + +1. Choose a **work folder** and an output file **prefix**. +2. Define the **layer stack** (materials, densities, thicknesses). +3. Set the **projectile** (species, energy, angle, spread, RNG, seed). +4. Optionally configure a **parameter scan** (energy, angles, counts, + thickness). +5. Run the simulation; inspect **Results** and export the ``.tgz`` archive + from the web UI when available. + +The desktop app bundles the engine on Linux and ships it through WSL2 on +Windows. The web edition runs the engine on the server via a CGI runner. diff --git a/docs/source/results.rst b/docs/source/results.rst new file mode 100644 index 0000000..53e0af7 --- /dev/null +++ b/docs/source/results.rst @@ -0,0 +1,12 @@ +Results +======= + +Profiles and layer fractions update as scan points complete. Use the +**Results** tab to inspect plots. + +In the **web** application, the status bar provides **Outputs** (download the +results archive, e.g. ``.tgz``) and **Details** (CGI and engine diagnostics). +Diagnostic text in the browser is not included in the downloaded archive. + +On desktop, outputs are written to the chosen work folder (plus any scan +subfolders defined by the workflow). diff --git a/docs/source/scans.rst b/docs/source/scans.rst new file mode 100644 index 0000000..6a75f56 --- /dev/null +++ b/docs/source/scans.rst @@ -0,0 +1,9 @@ +Parameter scans +=============== + +In the **Scan** tab you can sweep a parameter over a regular range or an +explicit list of values. The summary shows the number of points and (where +relevant) parallel workers before you start. + +Completed scan points may finish in arbitrary order; results are sorted by +scan value for plotting. diff --git a/docs/source/sharing.rst b/docs/source/sharing.rst new file mode 100644 index 0000000..903fae6 --- /dev/null +++ b/docs/source/sharing.rst @@ -0,0 +1,10 @@ +Sharing a setup +=============== + +The share button copies a link that encodes the current scientific +configuration (layers, projectile, scan, RNG, advanced settings) for the web +application. + +Links do **not** include local paths, output file prefixes, worker counts, +logs, or generated data. Recipients choose their own output locations before +running. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..800311c --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,24 @@ +Troubleshooting +=============== + +Desktop +------- + +* If the Windows engine fails to prepare, ensure WSL2 is installed and updated + (``wsl --status``, ``wsl --version``). See :doc:`install-windows`. +* If the app cannot find the engine on Linux, verify the packaged install + includes ``resources/bin/trimspNL`` or your configured binary path. + +Web +--- + +* Use **Details** in the status bar for CGI and engine output. +* Check file permissions and SELinux denials if runs fail to start. +* Ensure ``trimspNL`` is installed and executable at the path configured for + the CGI (default ``/usr/local/bin/trimspNL``). + +Reporting problems +------------------ + +Include the app/package version, platform, and relevant log excerpts or +**Details** output when reporting issues. diff --git a/docs/source/web-deployment.rst b/docs/source/web-deployment.rst new file mode 100644 index 0000000..c80acac --- /dev/null +++ b/docs/source/web-deployment.rst @@ -0,0 +1,11 @@ +Web deployment +============== + +The repository includes browser assets, a CGI runner (``singleTrimSP.cgi``), +and deployment scripts (``scripts/deploy-web.sh``, +``scripts/deploy-remote-web.sh``). See ``README.md`` and the comments in those +scripts for environment variables such as ``TRIMSP_BIN_PATH`` and +``TRIMSP_REMOTE_HOST``. + +On SELinux systems, review denied operations with ``ausearch -m avc -ts +recent`` if the CGI or engine cannot execute.