Merge pull request #10 from KWWyatt/merge-upstream-main

Merge upstreabgm main

Author: KWWyatt

.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`