ensemble-analyzer 1a0__tar.gz → 1.2__tar.gz

{ensemble_analyzer-1a0 → ensemble_analyzer-1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ensemble-analyzer
-Version: 1a0
+Version: 1.2
 Summary: Automatic Refinement of Conformational Ensemble
 Author-email: Andrea Pellegrini <andrea.pellegrini15@unibo.it>, Paolo Righi <paolo.righi@unibo.it>, Andrea Mazzanti <andrea.mazzanti@unibo.it>, Michele Mancinelli <michele.mancinelli@unibo.it>
 Maintainer-email: Andrea Pellegrini <andrea.pellegrini15@unibo.it>, Paolo Righi <paolo.righi@unibo.it>
@@ -15,27 +15,62 @@ Classifier: Topic :: Scientific/Engineering :: Chemistry
 Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: <3.15,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=2.2.0
-Requires-Dist: scipy>=1.16.3
-Requires-Dist: matplotlib>=3.10.7
-Requires-Dist: scikit-learn>=1.7.2
-Requires-Dist: ase>=3.24.0
-Requires-Dist: numba>=0.61.2
-Requires-Dist: tabulate>=0.9.0
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: scipy>=1.17.0
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: ase>=3.28.0
+Requires-Dist: numba>=0.65.0
+Requires-Dist: tabulate>=0.10.0
 Requires-Dist: InquirerPy>=0.3.4
+Requires-Dist: textual>=2.0.0
+Requires-Dist: sella>=2.4.0
+Requires-Dist: prism_pruner>=0.1.2
+Provides-Extra: tblite
+Requires-Dist: tblite; extra == "tblite"
+Provides-Extra: aimnet
+Requires-Dist: torch; extra == "aimnet"
+Requires-Dist: aimnet; extra == "aimnet"
+Provides-Extra: uma
+Requires-Dist: torch; extra == "uma"
+Requires-Dist: fairchem-core; extra == "uma"
+Provides-Extra: fairchem
+Requires-Dist: torch; extra == "fairchem"
+Requires-Dist: fairchem-core; extra == "fairchem"
+Provides-Extra: mace
+Requires-Dist: torch; extra == "mace"
+Requires-Dist: mace-torch; extra == "mace"
+Provides-Extra: skala
+Requires-Dist: torch; extra == "skala"
+Requires-Dist: skala; extra == "skala"
+Provides-Extra: ml
+Requires-Dist: tblite; extra == "ml"
+Requires-Dist: torch; extra == "ml"
+Requires-Dist: aimnet; extra == "ml"
+Requires-Dist: fairchem-core; extra == "ml"
+Requires-Dist: mace-torch; extra == "ml"
+Provides-Extra: all
+Requires-Dist: tblite; extra == "all"
+Requires-Dist: torch; extra == "all"
+Requires-Dist: aimnet; extra == "all"
+Requires-Dist: fairchem-core; extra == "all"
+Requires-Dist: mace-torch; extra == "all"
+Requires-Dist: skala; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
 Dynamic: license-file
 
 # Ensemble Analyzer <img src="logo.png" align="right" width="150">
-[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 ## Conformer Ensemble Pruning Software
@@ -48,7 +83,8 @@ Dynamic: license-file
 
 ### Core Capabilities
 - ⚡ **Multi-Protocol Workflows**: Sequential optimization/frequency calculations with automatic pruning
-- 🔬 **Quantum Chemistry Integration**: Support for ORCA and Gaussian
+- 🔬 **Quantum Chemistry Integration**: Support for ORCA, Gaussian, NWChem, semi-empirical (TBLite), and ML potentials (AIMNet)
+- 🧪 **Transition State Optimization**: TS mode validation with fragment localization, automatic displacement and re-optimization of spurious imaginary frequencies
 - 📊 **Advanced Clustering**: PCA-based conformer clustering with multiple feature extraction methods
 - 🎨 **Spectral Analysis**: Generate weighted IR, VCD, UV-vis, and ECD spectra
 - 🔄 **Checkpoint System**: Automatic restart capability with atomic file operations
@@ -64,21 +100,43 @@ Dynamic: license-file
 ## 📦 Installation
 
 ### Requirements
-- **Python** ≥ 3.11
+- **Python** 3.12 – 3.14
 - **Core**: NumPy, SciPy, Matplotlib, ASE
 - **Clustering**: scikit-learn
+- **Pruning**: [PRISM Pruner](https://github.com/ntampellini/prism_pruner)
 - **Acceleration**: Numba
 
 ```bash
+# Base install (ORCA/Gaussian only)
 pip install ensemble-analyzer
+
+# With ML potentials (TBLite, AIMNet, UMA, FairChem, MACE)
+pip install "ensemble-analyzer[ml]"
 ```
 
-- Install [ORCA](https://orcaforum.kofo.mpg.de/app.php/portal) from the ORCA Forum
-- *Optional*: Install Gaussian, if licensed
+### External QM Programs (optional)
+
+| Program | Requirement | Env Var |
+|---------|-------------|---------|
+| [ORCA](https://orcaforum.kofo.mpg.de/app.php/portal) | Installed binary | `ORCAVERSION="x.y.z"` |
+| [Gaussian](https://gaussian.com) | Licensed installation | — |
+| [NWChem](https://www.nwchem-sw.org) | Installed binary | `NWCHEMCOMMAND` or `PATH` |
+
+### Semi-empirical & ML Potentials (optional)
 
-- Export ORCA verion
+| Calculator | Type | Extra | Model Weights |
+|------------|------|-------|---------------|
+| **TBLite** | Semi-empirical (GFN-xTB) | `[tblite]` | Built-in |
+| **AIMNet** | ML potential | `[aimnet]` | `ENAN_MODELS_DIR/aimnet/` |
+| **UMA** | ML potential | `[uma]` | `ENAN_MODELS_DIR/uma/` |
+| **FairChem** | ML potential | `[fairchem]` | `ENAN_MODELS_DIR/fairchem/` |
+| **Mace** | ML potential | `[mace]` | `ENAN_MODELS_DIR/mace/` |
+
+
+Point to your model weights directory:
 ```bash
-export ORCAVERSION="x.y.z"
+export ENAN_MODELS_DIR="/path/to/ml_weights"
+# Default: ~/.ensemble_analyzer/models/<calculator>/
 ```
 
 ## 🚀 Quick Start
@@ -87,8 +145,8 @@ export ORCAVERSION="x.y.z"
 Create `protocol.json`
 ```json
 {
-    "0": {"funcional": "r2SCAN-3c", "opt": true, "freq": true,"cluster": 5, "comment": "Initial Optimization cluster into 5 families"},
-    "1": {"funcional": "wB97X-D4rev", "basis": "def2-QZVPPD", "comment": "Single Point energy evaluation"}
+    "0": {"functional": "r2SCAN-3c", "opt": true, "freq": true,"cluster": 5, "comment": "Initial Optimization cluster into 5 families"},
+    "1": {"functional": "wB97X-D4rev", "basis": "def2-QZVPPD", "comment": "Single Point energy evaluation"}
 }
 
 ```
@@ -98,7 +156,27 @@ Create `protocol.json`
 ensemble_analyzer --ensemble conformers.xyz --protocol protocol.json --output calculation.out --cpu 8 --temperature 298.15
 ```
 
-### 3. Restart from Checkpoint
+### 3. Using Semi-empirical & ML Potentials
+```json
+{
+    "0": {"calculator": "tblite", "functional": "GFN2-xTB", "opt": true, "freq": true},
+    "1": {"calculator": "aimnet", "functional": "<aimnet_weights.pt", "cluster": 10},
+}
+```
+
+ML calculators skip file I/O and parsing — energies are read directly from ASE atoms.
+
+### 4. Transition State Optimization with Mode Validation
+```json
+{
+    "0": {"calculator": "orca", "functional": "wB97X-D4rev", "basis": "def2-TZVPPD", "opt": true, "ts": true, "freq": true,
+          "loc_freq": [[0, 1, 2, 3], [4, 5, 6, 7, 8, 9]],
+          "comment": "TS optimization with fragment-based imag mode validation"}
+}
+```
+`ts: true` enables Sella optimizer for ML calculators and `OptTS`/`opt=(ts,…)` for QM programs. When `loc_freq` is set, the localization logic validates whether the imaginary frequency is mainly on the listed atom groups (`Frag1`, `Frag2`, …), displaces and re-optimizes when a spurious mode is detected.
+
+### 5. Restart from Checkpoint
 ```bash
 # Automatically resumes from last completed protocol
 ensemble_analyzer --restart
@@ -112,21 +190,33 @@ ensemble_analyzer --restart
 | **Calculation Settings** ||||
 | `functional` | str | DFT functional or method | `"B3LYP"`, `"xtb"`, `"HF-3c"` |
 | `basis` | str | Basis set (auto for composite methods) | `"def2-SVP"`, `"def2-TZVP"` |
-| `calculator` | str | QM program | `"orca"` (default), `"gaussian"` |
+| `calculator` | str | QM program / ML potential | `"orca"` (default), `"gaussian"`, `"nwchem"`, `"tblite"`, `"aimnet"` |
 | `opt` | bool | Optimize geometry | `true`, `false` |
 | `freq` | bool | Calculate frequencies | `true`, `false` |
 | `mult` | int | Spin multiplicity | `1` (singlet), `2` (doublet) |
-| `charge` | int | Molecular charge | |
-| `calculator` | str | Set the calculator | `orca` (default), `gaussian` |
+| `charge` | int | Molecular charge | `0` (default) |
+| `fmax` | float | Convergence threshold for ML optimizers (BFGS/Sella) [eV/Å] | `0.01` (default) |
+| `solvent` | dict | Implicit solvation | `{"solvent": "water", "smd": true}` |
+| **TS Analysis** ||||
+| `ts` | bool | Enable TS optimization (uses Sella for ML calculators) | `false` |
+| `loc_freq` | list[list] | Atom index groups for TS mode validation | `[[0,1,2], [3,4,5]]` |
+| `min_localization` | float | Min % displacement on `loc_freq` fragments to accept negative freq | `50.0` |
+| `auto_displace` | bool | Auto-displace along imaginary mode + re-optimize | `false` |
+| `displace_scale` | float | Displacement scale factor [Å] | `0.3` |
+| `neg_freq_threshold` | float | Frequencies with |ν| ≤ threshold treated as noise [cm⁻¹] | `20.0` |
 | **Pruning Thresholds** ||||
 | `thrG` | float | Energy similarity threshold [kcal/mol] | `3.0`, `5.0` |
-| `thrB` | float | Rotatory constant threshold [cm⁻¹] | `30.0`, `50.0` |
+| `thrB` | float | Rotatory constant threshold [cm⁻¹] | `5e-5`, `1e-5` |
 | `thrGMAX` | float | Energy window cutoff [kcal/mol] | `10.0` |
 | `cluster` | bool/int | Enable clustering | `true` (auto), `5` (fixed) |
 | `no_prune` | bool | Disable pruning | `false` (default) |
+| `prune_method` | str | Duplicate-removal backend: `rotconst` (E + rotational constants) or [PRISM Pruner](https://github.com/ntampellini/prism_pruner) `prism` / `prism_rotcorr` | `"rotconst"` (default) |
+| `prism_max_rmsd` | float | PRISM heavy-atom RMSD threshold [Å] (also `prism_max_dev`, `prism_moi`, `prism_moi_dev`, `prism_timeout`) | `0.25` |
+| **TD-DFT Settings** (Note: Not supported for MLIPs or tblite) ||||
+| `nroots` | int | Number of excited states for TD-DFT calculation | `10`, `30` |
+| `tda` | bool | Use Tamm-Dancoff approximation (ORCA defaults to `true`, set `false` for full TD-DFT) | `true`, `false` |
 | **Advanced** ||||
-| `solvent` | dict | Implicit solvation | `{"solvent": "water", "model": "SMD"}` |
-| `constrains` | list | Geometry constraints (only on cartesians)| `[1,2]` (fix cartesians) |
+| `constraints` | list[list] | Geometry constraints (only on cartesians)| `[[1,2],[1],[1,2,3],[4,3,2,1]]` |
 | `monitor_internals` | list | Track bond/angle/dihedral | `[[0,1], [0,1,2]]` |
 | `skip_opt_fail` | bool | Skip failed optimizations | `false` (default) |
 | `block_on_retention_rate` | bool | Block the calculation has a retention rate lower than the `MIN_RETENTION_RATE` (20%) | `false` (default) |
@@ -143,7 +233,7 @@ Feel free to browse all the possible protocol options and parameters.
 
 ### Regrapher
 
-If you want to change the convolution of your graphs, you can edit the setting.json file. Here, all the global settings are present. When finished, the command `enan_regraph` come handy. It re-run the Graph workflow with these new setting and in few time, you'll have your new graphs.
+If you want to change the convolution of your graphs, you can edit the `settings.json` file. Here, all the global settings are present. When finished, the command `enan_regraph` come handy. It re-run the Graph workflow with these new setting and in few time, you'll have your new graphs.
 ```bash
 usage: enan_regraph [-h] [-rb READ_BOLTZ] [-no-nm] [-w] [--disable-color] idx [idx ...]
 
@@ -164,7 +254,7 @@ options:
 All graphs are saved also as a pickle. This file can be reloaded and from there you can modify every single element of the Matplotlib Figure store in it. This requires some programming skills and, especially, time. Here is where `enan_graph_editor` comes to play. It is once again an interactive terminal interface (based both on rich or InquierPy library) where you can change and personalize every pickle. If you have to modify more files at once, a *batch* mode is implemented as well, so to by-pass the limitation of the manual selection of the interactive TUI. 
 
 ```bash
-usage: enan_graph_editor [-h] [--batch] [--list] [--rename OLD NEW] [--rename-file RENAME_FILE] [--color LABEL COLOR] [--linestyle LABEL STYLE] [--linewidth LABEL WIDTH] [--alpha LABEL ALPHA] [--output OUTPUT] [--format {pickle,png,pdf,svg}] [--preview] [--no-strict]
+usage: enan_graph_editor [-h] [--batch] [--list] [--rename OLD NEW] [--rename-file RENAME_FILE] [--color LABEL COLOR] [--linestyle LABEL STYLE] [--linewidth LABEL WIDTH] [--alpha LABEL ALPHA] [--visibility LABEL bool] [--output OUTPUT] [--format {pickle,png,pdf,svg}] [--no-strict]
                          [--verbose]
                          pickle_file
 
@@ -186,26 +276,48 @@ batch mode options:
   --rename-file RENAME_FILE, -rf RENAME_FILE
                         Mapping file OLD=NEW
   --color LABEL COLOR, -c LABEL COLOR
-                        Change colour
+                        Change color
   --linestyle LABEL STYLE, -ls LABEL STYLE
-                        Change line linestyle (e.g., -, --, :, -. )
+                        Change line style (e.g., -, --, :, -.)
   --linewidth LABEL WIDTH, -lw LABEL WIDTH
                         Change line linewidth (float)
   --alpha LABEL ALPHA, -a LABEL ALPHA
                         Change line transparency (0-1)
+  --visibility LABEL bool, -vis LABEL bool
+                        Toggle line visibility (True/False)
   --output OUTPUT, -o OUTPUT
                         Output file
   --format {pickle,png,pdf,svg}, -f {pickle,png,pdf,svg}
                         Output format
                         
 DEFAULT MODE: Interactive TUI
-  python enan_graph_editor plot.pkl
+  enan_graph_editor plot.pkl
 
 BATCH MODE (examples):
-  python enan_graph_editor plot.pkl --batch --list
-  python enan_graph_editor plot.pkl --batch --rename "Protocol 1" "Proto A"
-  python enan_graph_editor plot.pkl --batch --color "Experimental" red --output new.pkl
+  enan_graph_editor plot.pkl --batch --list
+  enan_graph_editor plot.pkl --batch --rename "Protocol 1" "Proto A"
+  enan_graph_editor plot.pkl --batch --color "Experimental" red --output new.pkl
 ```
+---
+
+## Cite
+
+```BibLaTex
+@article{
+  title = {Ensemble Analyzer: An Open-Source Python Framework for Automated Conformer Ensemble Refinement},
+  shorttitle = {Ensemble Analyzer},
+  author = {Pellegrini, Andrea and Righi, Paolo and Mazzanti, Andrea and Mancinelli, Michele},
+  date = {2026-05-11},
+  journaltitle = {Journal of Chemical Information and Modeling},
+  shortjournal = {J. Chem. Inf. Model.},
+  volume = {66},
+  number = {9},
+  pages = {5018--5025},
+  doi = {10.1021/acs.jcim.6c00273},
+  url = {https://pubs.acs.org/doi/10.1021/acs.jcim.6c00273},
+}
+```
+
 
 ---
 ## 🤝 Contributing
@@ -230,7 +342,7 @@ git push origin feature/awesome-feature
 
 ## 📄 License
 
-This software is licensed under the MIT-3.0 License. See the LICENSE file for details.
+This software is licensed under the MIT License. See the LICENSE file for details.
 
 ## 📞 Support and contact
 

ensemble_analyzer-1a0/src/ensemble_analyzer.egg-info/PKG-INFO → ensemble_analyzer-1.2/README.md

@@ -1,41 +1,5 @@
-Metadata-Version: 2.4
-Name: ensemble-analyzer
-Version: 1a0
-Summary: Automatic Refinement of Conformational Ensemble
-Author-email: Andrea Pellegrini <andrea.pellegrini15@unibo.it>, Paolo Righi <paolo.righi@unibo.it>, Andrea Mazzanti <andrea.mazzanti@unibo.it>, Michele Mancinelli <michele.mancinelli@unibo.it>
-Maintainer-email: Andrea Pellegrini <andrea.pellegrini15@unibo.it>, Paolo Righi <paolo.righi@unibo.it>
-License: MIT
-Project-URL: Homepage, https://github.com/andre-cloud/ensemble_analyzer
-Project-URL: Documentation, https://enan.readthedocs.io/en/latest/
-Keywords: computational-chemistry,conformational-analysis,ensemble-refinement,automatization,ase,quantum-chemistry
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Science/Research
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Scientific/Engineering :: Chemistry
-Classifier: Topic :: Scientific/Engineering :: Physics
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Operating System :: OS Independent
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=2.2.0
-Requires-Dist: scipy>=1.16.3
-Requires-Dist: matplotlib>=3.10.7
-Requires-Dist: scikit-learn>=1.7.2
-Requires-Dist: ase>=3.24.0
-Requires-Dist: numba>=0.61.2
-Requires-Dist: tabulate>=0.9.0
-Requires-Dist: InquirerPy>=0.3.4
-Dynamic: license-file
-
 # Ensemble Analyzer <img src="logo.png" align="right" width="150">
-[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 ## Conformer Ensemble Pruning Software
@@ -48,7 +12,8 @@ Dynamic: license-file
 
 ### Core Capabilities
 - ⚡ **Multi-Protocol Workflows**: Sequential optimization/frequency calculations with automatic pruning
-- 🔬 **Quantum Chemistry Integration**: Support for ORCA and Gaussian
+- 🔬 **Quantum Chemistry Integration**: Support for ORCA, Gaussian, NWChem, semi-empirical (TBLite), and ML potentials (AIMNet)
+- 🧪 **Transition State Optimization**: TS mode validation with fragment localization, automatic displacement and re-optimization of spurious imaginary frequencies
 - 📊 **Advanced Clustering**: PCA-based conformer clustering with multiple feature extraction methods
 - 🎨 **Spectral Analysis**: Generate weighted IR, VCD, UV-vis, and ECD spectra
 - 🔄 **Checkpoint System**: Automatic restart capability with atomic file operations
@@ -64,21 +29,43 @@ Dynamic: license-file
 ## 📦 Installation
 
 ### Requirements
-- **Python** ≥ 3.11
+- **Python** 3.12 – 3.14
 - **Core**: NumPy, SciPy, Matplotlib, ASE
 - **Clustering**: scikit-learn
+- **Pruning**: [PRISM Pruner](https://github.com/ntampellini/prism_pruner)
 - **Acceleration**: Numba
 
 ```bash
+# Base install (ORCA/Gaussian only)
 pip install ensemble-analyzer
+
+# With ML potentials (TBLite, AIMNet, UMA, FairChem, MACE)
+pip install "ensemble-analyzer[ml]"
 ```
 
-- Install [ORCA](https://orcaforum.kofo.mpg.de/app.php/portal) from the ORCA Forum
-- *Optional*: Install Gaussian, if licensed
+### External QM Programs (optional)
+
+| Program | Requirement | Env Var |
+|---------|-------------|---------|
+| [ORCA](https://orcaforum.kofo.mpg.de/app.php/portal) | Installed binary | `ORCAVERSION="x.y.z"` |
+| [Gaussian](https://gaussian.com) | Licensed installation | — |
+| [NWChem](https://www.nwchem-sw.org) | Installed binary | `NWCHEMCOMMAND` or `PATH` |
+
+### Semi-empirical & ML Potentials (optional)
+
+| Calculator | Type | Extra | Model Weights |
+|------------|------|-------|---------------|
+| **TBLite** | Semi-empirical (GFN-xTB) | `[tblite]` | Built-in |
+| **AIMNet** | ML potential | `[aimnet]` | `ENAN_MODELS_DIR/aimnet/` |
+| **UMA** | ML potential | `[uma]` | `ENAN_MODELS_DIR/uma/` |
+| **FairChem** | ML potential | `[fairchem]` | `ENAN_MODELS_DIR/fairchem/` |
+| **Mace** | ML potential | `[mace]` | `ENAN_MODELS_DIR/mace/` |
+
 
-- Export ORCA verion
+Point to your model weights directory:
 ```bash
-export ORCAVERSION="x.y.z"
+export ENAN_MODELS_DIR="/path/to/ml_weights"
+# Default: ~/.ensemble_analyzer/models/<calculator>/
 ```
 
 ## 🚀 Quick Start
@@ -87,8 +74,8 @@ export ORCAVERSION="x.y.z"
 Create `protocol.json`
 ```json
 {
-    "0": {"funcional": "r2SCAN-3c", "opt": true, "freq": true,"cluster": 5, "comment": "Initial Optimization cluster into 5 families"},
-    "1": {"funcional": "wB97X-D4rev", "basis": "def2-QZVPPD", "comment": "Single Point energy evaluation"}
+    "0": {"functional": "r2SCAN-3c", "opt": true, "freq": true,"cluster": 5, "comment": "Initial Optimization cluster into 5 families"},
+    "1": {"functional": "wB97X-D4rev", "basis": "def2-QZVPPD", "comment": "Single Point energy evaluation"}
 }
 
 ```
@@ -98,7 +85,27 @@ Create `protocol.json`
 ensemble_analyzer --ensemble conformers.xyz --protocol protocol.json --output calculation.out --cpu 8 --temperature 298.15
 ```
 
-### 3. Restart from Checkpoint
+### 3. Using Semi-empirical & ML Potentials
+```json
+{
+    "0": {"calculator": "tblite", "functional": "GFN2-xTB", "opt": true, "freq": true},
+    "1": {"calculator": "aimnet", "functional": "<aimnet_weights.pt", "cluster": 10},
+}
+```
+
+ML calculators skip file I/O and parsing — energies are read directly from ASE atoms.
+
+### 4. Transition State Optimization with Mode Validation
+```json
+{
+    "0": {"calculator": "orca", "functional": "wB97X-D4rev", "basis": "def2-TZVPPD", "opt": true, "ts": true, "freq": true,
+          "loc_freq": [[0, 1, 2, 3], [4, 5, 6, 7, 8, 9]],
+          "comment": "TS optimization with fragment-based imag mode validation"}
+}
+```
+`ts: true` enables Sella optimizer for ML calculators and `OptTS`/`opt=(ts,…)` for QM programs. When `loc_freq` is set, the localization logic validates whether the imaginary frequency is mainly on the listed atom groups (`Frag1`, `Frag2`, …), displaces and re-optimizes when a spurious mode is detected.
+
+### 5. Restart from Checkpoint
 ```bash
 # Automatically resumes from last completed protocol
 ensemble_analyzer --restart
@@ -112,21 +119,33 @@ ensemble_analyzer --restart
 | **Calculation Settings** ||||
 | `functional` | str | DFT functional or method | `"B3LYP"`, `"xtb"`, `"HF-3c"` |
 | `basis` | str | Basis set (auto for composite methods) | `"def2-SVP"`, `"def2-TZVP"` |
-| `calculator` | str | QM program | `"orca"` (default), `"gaussian"` |
+| `calculator` | str | QM program / ML potential | `"orca"` (default), `"gaussian"`, `"nwchem"`, `"tblite"`, `"aimnet"` |
 | `opt` | bool | Optimize geometry | `true`, `false` |
 | `freq` | bool | Calculate frequencies | `true`, `false` |
 | `mult` | int | Spin multiplicity | `1` (singlet), `2` (doublet) |
-| `charge` | int | Molecular charge | |
-| `calculator` | str | Set the calculator | `orca` (default), `gaussian` |
+| `charge` | int | Molecular charge | `0` (default) |
+| `fmax` | float | Convergence threshold for ML optimizers (BFGS/Sella) [eV/Å] | `0.01` (default) |
+| `solvent` | dict | Implicit solvation | `{"solvent": "water", "smd": true}` |
+| **TS Analysis** ||||
+| `ts` | bool | Enable TS optimization (uses Sella for ML calculators) | `false` |
+| `loc_freq` | list[list] | Atom index groups for TS mode validation | `[[0,1,2], [3,4,5]]` |
+| `min_localization` | float | Min % displacement on `loc_freq` fragments to accept negative freq | `50.0` |
+| `auto_displace` | bool | Auto-displace along imaginary mode + re-optimize | `false` |
+| `displace_scale` | float | Displacement scale factor [Å] | `0.3` |
+| `neg_freq_threshold` | float | Frequencies with |ν| ≤ threshold treated as noise [cm⁻¹] | `20.0` |
 | **Pruning Thresholds** ||||
 | `thrG` | float | Energy similarity threshold [kcal/mol] | `3.0`, `5.0` |
-| `thrB` | float | Rotatory constant threshold [cm⁻¹] | `30.0`, `50.0` |
+| `thrB` | float | Rotatory constant threshold [cm⁻¹] | `5e-5`, `1e-5` |
 | `thrGMAX` | float | Energy window cutoff [kcal/mol] | `10.0` |
 | `cluster` | bool/int | Enable clustering | `true` (auto), `5` (fixed) |
 | `no_prune` | bool | Disable pruning | `false` (default) |
+| `prune_method` | str | Duplicate-removal backend: `rotconst` (E + rotational constants) or [PRISM Pruner](https://github.com/ntampellini/prism_pruner) `prism` / `prism_rotcorr` | `"rotconst"` (default) |
+| `prism_max_rmsd` | float | PRISM heavy-atom RMSD threshold [Å] (also `prism_max_dev`, `prism_moi`, `prism_moi_dev`, `prism_timeout`) | `0.25` |
+| **TD-DFT Settings** (Note: Not supported for MLIPs or tblite) ||||
+| `nroots` | int | Number of excited states for TD-DFT calculation | `10`, `30` |
+| `tda` | bool | Use Tamm-Dancoff approximation (ORCA defaults to `true`, set `false` for full TD-DFT) | `true`, `false` |
 | **Advanced** ||||
-| `solvent` | dict | Implicit solvation | `{"solvent": "water", "model": "SMD"}` |
-| `constrains` | list | Geometry constraints (only on cartesians)| `[1,2]` (fix cartesians) |
+| `constraints` | list[list] | Geometry constraints (only on cartesians)| `[[1,2],[1],[1,2,3],[4,3,2,1]]` |
 | `monitor_internals` | list | Track bond/angle/dihedral | `[[0,1], [0,1,2]]` |
 | `skip_opt_fail` | bool | Skip failed optimizations | `false` (default) |
 | `block_on_retention_rate` | bool | Block the calculation has a retention rate lower than the `MIN_RETENTION_RATE` (20%) | `false` (default) |
@@ -143,7 +162,7 @@ Feel free to browse all the possible protocol options and parameters.
 
 ### Regrapher
 
-If you want to change the convolution of your graphs, you can edit the setting.json file. Here, all the global settings are present. When finished, the command `enan_regraph` come handy. It re-run the Graph workflow with these new setting and in few time, you'll have your new graphs.
+If you want to change the convolution of your graphs, you can edit the `settings.json` file. Here, all the global settings are present. When finished, the command `enan_regraph` come handy. It re-run the Graph workflow with these new setting and in few time, you'll have your new graphs.
 ```bash
 usage: enan_regraph [-h] [-rb READ_BOLTZ] [-no-nm] [-w] [--disable-color] idx [idx ...]
 
@@ -164,7 +183,7 @@ options:
 All graphs are saved also as a pickle. This file can be reloaded and from there you can modify every single element of the Matplotlib Figure store in it. This requires some programming skills and, especially, time. Here is where `enan_graph_editor` comes to play. It is once again an interactive terminal interface (based both on rich or InquierPy library) where you can change and personalize every pickle. If you have to modify more files at once, a *batch* mode is implemented as well, so to by-pass the limitation of the manual selection of the interactive TUI. 
 
 ```bash
-usage: enan_graph_editor [-h] [--batch] [--list] [--rename OLD NEW] [--rename-file RENAME_FILE] [--color LABEL COLOR] [--linestyle LABEL STYLE] [--linewidth LABEL WIDTH] [--alpha LABEL ALPHA] [--output OUTPUT] [--format {pickle,png,pdf,svg}] [--preview] [--no-strict]
+usage: enan_graph_editor [-h] [--batch] [--list] [--rename OLD NEW] [--rename-file RENAME_FILE] [--color LABEL COLOR] [--linestyle LABEL STYLE] [--linewidth LABEL WIDTH] [--alpha LABEL ALPHA] [--visibility LABEL bool] [--output OUTPUT] [--format {pickle,png,pdf,svg}] [--no-strict]
                          [--verbose]
                          pickle_file
 
@@ -186,26 +205,48 @@ batch mode options:
   --rename-file RENAME_FILE, -rf RENAME_FILE
                         Mapping file OLD=NEW
   --color LABEL COLOR, -c LABEL COLOR
-                        Change colour
+                        Change color
   --linestyle LABEL STYLE, -ls LABEL STYLE
-                        Change line linestyle (e.g., -, --, :, -. )
+                        Change line style (e.g., -, --, :, -.)
   --linewidth LABEL WIDTH, -lw LABEL WIDTH
                         Change line linewidth (float)
   --alpha LABEL ALPHA, -a LABEL ALPHA
                         Change line transparency (0-1)
+  --visibility LABEL bool, -vis LABEL bool
+                        Toggle line visibility (True/False)
   --output OUTPUT, -o OUTPUT
                         Output file
   --format {pickle,png,pdf,svg}, -f {pickle,png,pdf,svg}
                         Output format
                         
 DEFAULT MODE: Interactive TUI
-  python enan_graph_editor plot.pkl
+  enan_graph_editor plot.pkl
 
 BATCH MODE (examples):
-  python enan_graph_editor plot.pkl --batch --list
-  python enan_graph_editor plot.pkl --batch --rename "Protocol 1" "Proto A"
-  python enan_graph_editor plot.pkl --batch --color "Experimental" red --output new.pkl
+  enan_graph_editor plot.pkl --batch --list
+  enan_graph_editor plot.pkl --batch --rename "Protocol 1" "Proto A"
+  enan_graph_editor plot.pkl --batch --color "Experimental" red --output new.pkl
 ```
+---
+
+## Cite
+
+```BibLaTex
+@article{
+  title = {Ensemble Analyzer: An Open-Source Python Framework for Automated Conformer Ensemble Refinement},
+  shorttitle = {Ensemble Analyzer},
+  author = {Pellegrini, Andrea and Righi, Paolo and Mazzanti, Andrea and Mancinelli, Michele},
+  date = {2026-05-11},
+  journaltitle = {Journal of Chemical Information and Modeling},
+  shortjournal = {J. Chem. Inf. Model.},
+  volume = {66},
+  number = {9},
+  pages = {5018--5025},
+  doi = {10.1021/acs.jcim.6c00273},
+  url = {https://pubs.acs.org/doi/10.1021/acs.jcim.6c00273},
+}
+```
+
 
 ---
 ## 🤝 Contributing
@@ -230,7 +271,7 @@ git push origin feature/awesome-feature
 
 ## 📄 License
 
-This software is licensed under the MIT-3.0 License. See the LICENSE file for details.
+This software is licensed under the MIT License. See the LICENSE file for details.
 
 ## 📞 Support and contact