Rmcsetup

.codespellignore

@@ -1 +1,2 @@
 Te
+Nd

README.md

@@ -39,6 +39,13 @@ repository conda environment file.
 ```bash
 git clone https://github.com/kewh5868/SAXSShell.git
 cd SAXSShell
+```
+
+### macOS, Linux, and WSL
+
+Create the Python 3.12 conda environment from the default environment file:
+
+```bash
 conda env create -f requirements/saxshell-py312.yml
 ```
 
@@ -55,6 +62,44 @@ Launch the main SAXSShell application from the repository root:
 PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
 ```
 
+### Native Windows
+
+On native Windows, use the Windows-specific environment file:
+
+```cmd
+conda env create -f requirements\saxshell-py312-win.yml
+```
+
+If the `saxshell-py312` environment already exists, update it from the same
+file:
+
+```cmd
+conda env update -n saxshell-py312 -f requirements\saxshell-py312-win.yml --prune
+```
+
+From Anaconda Prompt, activate the environment, set `PYTHONPATH`, and launch
+the SAXS UI:
+
+```cmd
+conda activate saxshell-py312
+set PYTHONPATH=src
+python -m saxshell.saxs
+```
+
+You can also launch without activating the environment:
+
+```cmd
+set PYTHONPATH=src
+conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
+```
+
+From Windows PowerShell, set `PYTHONPATH` with PowerShell syntax:
+
+```powershell
+$env:PYTHONPATH = "src"
+conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
+```
+
 ## First Project
 
 Start by preparing the simulation data that the SAXS project will consume:

README.rst

@@ -60,13 +60,19 @@ Installation
 ------------
 
 SAXSShell is not pip-installable yet. The current user-facing path is to clone
-the repository and create the conda environment from the checked-in
-``requirements/saxshell-py312.yml`` file.
+the repository and create the conda environment from the checked-in environment
+file for your platform.
 
 From a terminal, run ::
 
         git clone https://github.com/kewh5868/SAXSShell.git
         cd SAXSShell
+
+macOS, Linux, and WSL
+~~~~~~~~~~~~~~~~~~~~~
+
+Create the Python 3.12 conda environment from the default environment file ::
+
         conda env create -f requirements/saxshell-py312.yml
 
 If the environment already exists, update it with ::
@@ -77,6 +83,35 @@ Launch the main SAXSShell application from the repository root with ::
 
         PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
 
+Native Windows
+~~~~~~~~~~~~~~
+
+On native Windows, create the environment from the Windows-specific environment
+file ::
+
+        conda env create -f requirements\saxshell-py312-win.yml
+
+If the environment already exists, update it with ::
+
+        conda env update -n saxshell-py312 -f requirements\saxshell-py312-win.yml --prune
+
+From Anaconda Prompt, activate the environment, set ``PYTHONPATH``, and launch
+the SAXS UI ::
+
+        conda activate saxshell-py312
+        set PYTHONPATH=src
+        python -m saxshell.saxs
+
+You can also launch without activating the environment ::
+
+        set PYTHONPATH=src
+        conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
+
+From Windows PowerShell, set ``PYTHONPATH`` with PowerShell syntax ::
+
+        $env:PYTHONPATH = "src"
+        conda run --no-capture-output -n saxshell-py312 python -m saxshell.saxs
+
 You can also verify that the source checkout imports inside the conda
 environment with ::
 

docs/getting-started/project-setup.md

@@ -108,14 +108,21 @@ The **Component build mode** dropdown controls what happens when you click
 Representative structures are optional project-backed files that compatible
 Debye, Born, FFT, and RMCSetup workflows can use instead of average cluster
 folders. Use **Tools > Structure Analysis > Open Representative Structures** for
-the full interactive analysis UI, or use **Tools > (beta) > Open Representative
-CLI Setup (Beta)** to save `representative_structure_cli_run.json` and run the
-same backend from the source checkout:
+the full interactive analysis UI, or use **Tools > CLI Setup > Open
+Representative CLI Setup (Beta)** to save
+`representative_structure_cli_run.json` and run the same backend from the
+source checkout:
 
 ```bash
 PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.representativefinder run /path/to/project
 ```
 
+The same **Tools > CLI Setup** menu can prepare project-local run files for
+XYZ-to-PDB conversion, cluster extraction, cluster dynamics, and cluster
+dynamics ML. Those run files let you run long jobs from a terminal or batch
+several prepared project folders while keeping outputs linked back to their
+projects.
+
 ## Debye-Waller factors
 
 **Compute Debye-Waller Factors (beta)** is an optional linked step in Project

docs/getting-started/quickstart.md

@@ -18,8 +18,8 @@ that downstream tools should use:
 
 ```bash
 PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory inspect traj.xyz --energy-file traj.ener
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 3
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 3
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 2
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 2
 ```
 
 If residue identity matters for your downstream analysis, convert the exported

docs/tutorials/example-workflow.md

@@ -20,7 +20,7 @@ PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshel
 Use either a manual cutoff or the suggested one:
 
 ```bash
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 3
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 2
 ```
 
 ## Step 3: convert to PDB only if needed

docs/tutorials/md-to-saxs-pipeline.md

@@ -19,8 +19,8 @@ commands from the repository root.
 
 ```bash
 PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory inspect traj.xyz --energy-file traj.ener
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 3
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 3
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 2
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 2
 ```
 
 ## Convert to residue-aware PDB, if needed

docs/user-guide/cluster-dynamics-ml.md

@@ -62,6 +62,42 @@ plus a structure library for the observed smaller clusters.
    `SAXS` tabs.
 10. Save the dataset, CSV exports, or a detailed PowerPoint report if needed.
 
+## Project-Backed CLI Setup
+
+For background prediction runs, use **Tools > CLI Setup > Open Cluster Dynamics
+ML CLI Setup (Beta)**. The setup window writes
+`cluster_dynamics_ml_cli_run.json` in the active project folder and shows the
+terminal commands to run later:
+
+```bash
+clusterdynamicsml run /path/to/project
+saxshell clusterdynamicsml run /path/to/project
+```
+
+The command reads the project-local run file, runs the same prediction backend
+used by the UI, and saves the reloadable JSON dataset plus companion CSV files,
+predicted structures, SAXS profiles, histogram exports, and the inherited
+cluster-dynamics heatmap/lifetime exports under
+`exported_results/data/clusterdynamicsml` by default. It refreshes the
+project's registered frames, clusters, energy, and experimental-data references
+when a `saxs_project.json` file is present.
+
+You can launch the setup window directly:
+
+```bash
+clusterdynamicsml setup-ui /path/to/project
+```
+
+To process several prepared projects from one terminal session, use:
+
+```bash
+clusterdynamicsml batch-run /path/to/project_a /path/to/project_b --workers 2 --keep-going
+```
+
+Each project keeps its own run file and output dataset. The CLI path is
+separate from the interactive UI, so the existing tabs, cached-history browser,
+and plotting controls remain UI-only.
+
 ## Training data assembled by the workflow
 
 The workflow first runs the standard cluster-dynamics analysis and then joins

docs/user-guide/cluster-dynamics.md

@@ -78,6 +78,40 @@ times, not the folder label.
 If the tool is launched from the main SAXS UI, it inherits the active project
 directory automatically.
 
+## Project-Backed CLI Setup
+
+For longer cluster-dynamics runs, use **Tools > CLI Setup > Open Cluster
+Dynamics CLI Setup (Beta)**. The setup window writes
+`cluster_dynamics_cli_run.json` in the active project folder and shows the
+terminal commands to run later:
+
+```bash
+clusterdynamics run /path/to/project
+saxshell clusterdynamics run /path/to/project
+```
+
+The command reads the project-local run file, runs the same backend used by the
+UI, and saves the reloadable JSON dataset plus the heatmap CSV, lifetime CSV,
+and optional energy CSV under `exported_results/data/clusterdynamics` by
+default. It also refreshes the project's registered frames and energy-file
+references when a `saxs_project.json` file is present.
+
+You can also launch the setup window directly:
+
+```bash
+clusterdynamics setup-ui /path/to/project
+```
+
+To process several prepared projects from one terminal session, use:
+
+```bash
+clusterdynamics batch-run /path/to/project_a /path/to/project_b --workers 2 --keep-going
+```
+
+Each project keeps its own run file and output dataset, so these runs can also
+be started in separate terminals or background jobs without touching the
+interactive plotting workflow.
+
 ## Saved Outputs
 
 The save action writes a JSON dataset plus companion CSV files beside it:

docs/user-guide/cluster-extraction.md

@@ -34,8 +34,8 @@ Example:
 
 ```bash
 PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory inspect traj.xyz --energy-file traj.ener
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 3
-PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 3
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory suggest-cutoff traj.xyz --energy-file traj.ener --temp-target-k 300 --window 2
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.mdtrajectory export traj.xyz --energy-file traj.ener --use-suggested-cutoff --temp-target-k 300 --window 2
 ```
 
 When a cutoff is applied, the default folder name now uses the form
@@ -76,6 +76,36 @@ The cluster workflow supports both UI and CLI usage. Its CLI exposes separate
 The CLI help text explicitly calls out faster neighbor search modes such as
 `kdtree` and `vectorized`.
 
+### Project-backed cluster run files
+
+For repeatable project runs, launch the setup window and save a run file in the
+SAXSShell project folder:
+
+From the main SAXSShell window, use **Tools > CLI Setup > Open Cluster
+Extraction CLI Setup (Beta)**. The same setup window can also be launched from
+a terminal:
+
+```bash
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.cluster setup-ui /path/to/saxs_project
+```
+
+The setup window records the project folder, extracted frames folder, output
+clusters folder, atom rules, pair cutoffs, PBC/box settings, shell options, and
+neighbor-search settings in `cluster_extraction_cli_run.json`. Paths inside the
+project are stored relative to the project folder so the project can move as a
+unit.
+
+After saving, run the extraction from the terminal:
+
+```bash
+PYTHONPATH=src conda run --no-capture-output -n saxshell-py312 python -m saxshell.cluster run /path/to/saxs_project
+```
+
+Use `--run-file custom_run.json` to run a different JSON file. Relative
+`--run-file` paths are resolved against the project folder. A completed run
+updates the project `clusters_dir` reference to the output folder while leaving
+the existing frames and PDB-frames references unchanged.
+
 ## `clusterdynamics`
 
 This application consumes the extracted XYZ or PDB frames from `mdtrajectory`

docs/user-guide/gui-overview.md

@@ -193,6 +193,33 @@ settings outside the main computed-distribution flow.
 Use this section for smaller estimate windows such as volume-fraction, number
 density, attenuation, and fluorescence calculators.
 
+### CLI Setup
+
+Use this section when you want the GUI to prepare a project-local run file, but
+you want the heavier work to run later from a terminal.
+
+- `XYZ -> PDB CLI Setup` saves `xyz2pdb_cli_run.json` in the project folder so
+  `xyz2pdb run /path/to/project` can convert XYZ frames to PDB frames and
+  register the PDB output folder with the project.
+- `Cluster Extraction CLI Setup` saves `cluster_extraction_cli_run.json` in the
+  project folder so `clusters run /path/to/project` can export clusters and
+  register the clusters output folder with the project.
+- `Cluster Dynamics CLI Setup` saves `cluster_dynamics_cli_run.json` in the
+  project folder so `clusterdynamics run /path/to/project` can generate the
+  time-binned heatmap dataset, cluster lifetime table, and association /
+  dissociation rate exports from the terminal.
+- `Cluster Dynamics ML CLI Setup` saves `cluster_dynamics_ml_cli_run.json` in
+  the project folder so `clusterdynamicsml run /path/to/project` can run the
+  prediction workflow, write predicted structures and SAXS/profile exports,
+  and keep the outputs linked to the project folder.
+- `Representative CLI Setup` saves `representative_structure_cli_run.json` in
+  the project folder so `representativefinder run /path/to/project` can execute
+  the representative-selection backend without the plotting and viewer UI.
+
+Cluster Dynamics and Cluster Dynamics ML also provide `batch-run --workers N`
+subcommands for processing multiple prepared project folders from one terminal
+session.
+
 ### (beta)
 
 Use this section for early-access workflows that are exposed from the main
@@ -201,10 +228,6 @@ Use this section for early-access workflows that are exposed from the main
 - `Debye-Waller Analysis` estimates intra-molecular and inter-molecular
   Debye-Waller coefficients from sorted PDB cluster folders and saves them in
   the active project when requested from Project Setup or the Tools menu.
-- `Representative CLI Setup` saves
-  `representative_structure_cli_run.json` in the project folder so
-  the `representativefinder` source module can execute the same representative
-  selection without the plotting and viewer UI.
 
 !!! warning "Debye-Waller status"
 The linked **Compute Debye-Waller Factors (beta)** workflow is currently