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:
1 parent
cf4eeaf06c
commit
0a86f85231
18 files changed
+450
No files matched your search
@@ -0,0 +1 @@
|
||||
/_build/
|
||||
@@ -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)
|
||||
@@ -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
|
||||
Whitespace-only changes.
@@ -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.
|
||||
@@ -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,
|
||||
),
|
||||
]
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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>`_.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user