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'.
This commit is contained in:
salman committed 2026-11-16 10:32:05 +01:00
1 parent cf4eeaf06c
commit 0a86f85231
18 files changed
+450

No files matched your search

+1
View File
@@ -0,0 +1 @@
/_build/
+15
View File
@@ -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)
+35
View File
@@ -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
View File
Whitespace-only changes.
+14
View File
@@ -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.
+63
View File
@@ -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,
),
]
+29
View File
@@ -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.
+15
View File
@@ -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.
+34
View File
@@ -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 <mailto:zaher.salman@psi.ch>`_.
+63
View File
@@ -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 ``<version>``
with the package version you obtained.
Install from a package
----------------------
RPM
~~~
.. code-block:: bash
sudo dnf install ./trimsp-<version>-1.x86_64.rpm
trimsp
DEB
~~~
.. code-block:: bash
sudo apt install ./trimsp_<version>_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
+71
View File
@@ -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\<you>\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.
+21
View File
@@ -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.
+23
View File
@@ -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.
+12
View File
@@ -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).
+9
View File
@@ -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.
+10
View File
@@ -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.
+24
View File
@@ -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.
+11
View File
@@ -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.