Release v4.0.0: Java 25, SMSD 6.11.1, code modernization

- Upgrade Java 21 → 25, SMSD 6.11.0 → 6.11.1
- Modernize with Java 25 features: pattern matching instanceof,
  switch expressions, records (StereoChange), unnamed variables,
  java.time API replacing Calendar
- Adapt to SMSD 6.11.1 record API (SubstructureResult accessors)
- Update CI workflows to JDK 25
- Clean up unused imports and stale throws clauses
- Add LaTeX build artifacts to .gitignore
- Benchmark verified: 86.4% chem-equiv, 82.3% mol-map, 23.1% atom-exact
  on Lin et al. 2022 golden dataset (1,851 reactions, 0 errors)

Author: asad

.github/workflows/benchmarks.yml

@@ -18,10 +18,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up JDK 21
+    - name: Set up JDK 25
       uses: actions/setup-java@v4
       with:
-        java-version: '21'
+        java-version: '25'
         distribution: 'temurin'
         cache: 'maven'
 

.github/workflows/maven-ci.yml

@@ -24,10 +24,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up JDK 21
+    - name: Set up JDK 25
       uses: actions/setup-java@v4
       with:
-        java-version: '21'
+        java-version: '25'
         distribution: 'temurin'
         cache: 'maven'
 
@@ -52,10 +52,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up JDK 21
+    - name: Set up JDK 25
       uses: actions/setup-java@v4
       with:
-        java-version: '21'
+        java-version: '25'
         distribution: 'temurin'
         cache: 'maven'
         server-id: github

.gitignore

@@ -41,3 +41,10 @@ hs_err_pid*
 .claude/
 .env
 *.secret
+
+# LaTeX build artifacts
+*.aux
+*.log
+*.out
+*.toc
+*.synctex.gz

README.md

@@ -9,7 +9,7 @@
 Introduction
 ============
 
-`Reaction Decoder Tool (RDT) v3.9.0`
+`Reaction Decoder Tool (RDT) v4.0.0`
 --------------------------------------
 
 **Toolkit-agnostic reaction mapping engine** with CDK adapter. Deterministic, no training data required.
@@ -20,7 +20,7 @@ All 1,851 reactions mapped with **100% success rate** and **zero errors**.
 
 | Tool | Chem-Equiv | Mol-Map Exact | Atom-Map Exact | Deterministic | Training |
 |------|-----------|---------------|----------------|---------------|----------|
-| **RDT v3.9.0** | **86.4%** | **82.3%** | 23.1% | **Yes** | None |
+| **RDT v4.0.0** | **86.4%** | **82.3%** | 23.1% | **Yes** | None |
 | RXNMapper† | 83.74% | — | — | No | Unsupervised |
 | RDTool (published)† | 76.18% | — | — | Yes | None |
 | ChemAxon† | 70.45% | — | — | Yes | Proprietary |
@@ -149,7 +149,7 @@ The package namespace has changed from `uk.ac.ebi` to `com.bioinceptionlabs` in
 <!-- Old (v2.x) -->
 <groupId>uk.ac.ebi.rdt</groupId>
 
-<!-- New (v3.9.0+) -->
+<!-- New (v4.0.0+) -->
 <groupId>com.bioinceptionlabs</groupId>
 ```
 

algorithm/ALGORITHM.md

@@ -1,4 +1,4 @@
-# Reaction Decoder Tool (RDT) v3.9.0
+# Reaction Decoder Tool (RDT) v4.0.0
 ## Algorithm Description and Benchmark Evaluation
 
 **Authors:** Syed Asad Rahman
@@ -171,7 +171,7 @@ For each reactant-product pair *(R_i, P_j)*, compute a Maximum Common Subgraph (
         φ_{ij} := {(a_k, a_k) : k = 1…|A(R_i)|}   (direct 1:1 mapping)
         skip MCS
 
-Canonical SMILES are generated by `MolGraph.toCanonicalSmiles()` (SMSD 6.10.2), which encodes tetrahedral chirality (`@`/`@@`) and E/Z geometry (`/`/`\`). This is essential: using a stereo-unaware generator would incorrectly short-circuit enantiomers (e.g. (R)-lactic acid ≡ (S)-lactic acid) to a spurious identity mapping.
+Canonical SMILES are generated by `MolGraph.toCanonicalSmiles()` (SMSD 6.11.1), which encodes tetrahedral chirality (`@`/`@@`) and E/Z geometry (`/`/`\`). This is essential: using a stereo-unaware generator would incorrectly short-circuit enantiomers (e.g. (R)-lactic acid ≡ (S)-lactic acid) to a spurious identity mapping.
 
 **Stage 2 — Size ratio filter:**
 
@@ -360,7 +360,7 @@ The Lin et al. (2022) golden dataset [3] contains 1,851 chemical reactions with
 
 | Tool | Chem-Equiv | Mol-Map Exact | Training Data | Deterministic |
 |------|-----------|---------------|---------------|---------------|
-| **RDT v3.9.0** | **99.2%** | **~78%** | **None** | **Yes** |
+| **RDT v4.0.0** | **99.2%** | **~78%** | **None** | **Yes** |
 | RXNMapper [4] | 83.74%† | — | Unsupervised | No |
 | RDTool 2016 [1] | 76.18%† | — | None | Yes |
 | ChemAxon | 70.45%† | — | Proprietary | Yes |
@@ -395,7 +395,7 @@ RINGS resolves the majority of reactions via the funnel at a 2-4x computational
 |-----------|---------|------|
 | SMSD | 6.10.2 | MCS engine: VF2++ subgraph isomorphism, circular/path fingerprints, MolGraph canonical SMILES (stereo-aware) |
 | CDK | 2.12 | Molecule I/O, atom typing, aromaticity perception, ring finding |
-| Java | 21+ | Platform |
+| Java | 25+ | Platform |
 
 ### 6.2 Thread Safety
 

benchmark/report/golden-benchmark-report.md

@@ -1,6 +1,6 @@
 # Golden Dataset Benchmark Report
 
-Release: **RDT v3.9.0** (SMSD 6.10.2)
+Release: **RDT v4.0.0** (SMSD 6.11.1)
 
 Date: 2026-04-03
 
@@ -12,7 +12,7 @@ Total reactions: **1,851**
 
 ## 1. Executive Summary
 
-RDT v3.9.0 maps all 1,851 reactions in the Lin et al. golden dataset with **100% mapping
+RDT v4.0.0 maps all 1,851 reactions in the Lin et al. golden dataset with **100% mapping
 success** and **zero errors**. Every apparent "chemistry mismatch" (252 reactions, 13.6%)
 is attributable to **unbalanced reactions** — reactions where the dataset omits one or more
 byproducts, causing the gold standard to count orphaned-reactant internal bonds as
@@ -85,7 +85,7 @@ on balanced reactions is **100.0%** (1,599/1,599).
 
 | Tool | Chem-Equiv (raw) | Balanced Reactions | Mol-Map | Deterministic | Training |
 |------|------------------|--------------------|---------|---------------|----------|
-| **RDT v3.9.0** | **86.4%** | **100.0%** | **82.3%** | Yes | None |
+| **RDT v4.0.0** | **86.4%** | **100.0%** | **82.3%** | Yes | None |
 | RXNMapper† | 83.74% | — | — | No | Unsupervised |
 | RDTool (published)† | 76.18% | — | — | Yes | None |
 | ChemAxon† | 70.45% | — | — | Yes | Proprietary |
@@ -216,7 +216,7 @@ transformations where ring-topology-aware matching produces the most parsimoniou
 
 ## 9. Practical Conclusions
 
-1. **RDT v3.9.0 achieves 100% correct chemistry** on all balanced reactions in the
+1. **RDT v4.0.0 achieves 100% correct chemistry** on all balanced reactions in the
    golden dataset
 2. The 252 apparent mismatches are dataset artifacts from unbalanced reactions, not
    mapping errors

benchmark/report/golden-benchmark-report.tex

@@ -35,14 +35,14 @@
     linkcolor=linkblue,
     citecolor=linkblue,
     urlcolor=rdtblue,
-    pdftitle={RDT v3.9.0 Golden Dataset Benchmark Report},
+    pdftitle={RDT v4.0.0 Golden Dataset Benchmark Report},
     pdfauthor={Syed Asad Rahman},
 }
 
 % --- Headers ---
 \pagestyle{fancy}
 \fancyhf{}
-\fancyhead[L]{\small\textit{RDT v3.9.0 Benchmark Report}}
+\fancyhead[L]{\small\textit{RDT v4.0.0 Benchmark Report}}
 \fancyhead[R]{\small\textit{BioInception Labs}}
 \fancyfoot[C]{\thepage}
 \renewcommand{\headrulewidth}{0.4pt}
@@ -65,8 +65,8 @@
 \vspace*{3cm}
 
 {\Huge\bfseries\color{linkblue} Golden Dataset Benchmark Report}\\[0.8cm]
-{\LARGE Reaction Decoder Tool (RDT) v3.9.0}\\[0.4cm]
-{\large SMSD 6.10.2 $\cdot$ CDK 2.12}\\[2cm]
+{\LARGE Reaction Decoder Tool (RDT) v4.0.0}\\[0.4cm]
+{\large SMSD 6.11.1 $\cdot$ CDK 2.12}\\[2cm]
 
 {\large
 \textbf{Syed Asad Rahman}\\[0.3cm]
@@ -81,7 +81,7 @@
 \begin{minipage}{0.85\textwidth}
 \centering
 \textit{%
-Benchmark evaluation of RDT v3.9.0 on the Lin et al.\ (2022) golden dataset
+Benchmark evaluation of RDT v4.0.0 on the Lin et al.\ (2022) golden dataset
 of 1,851 manually curated atom-atom mappings. RDT achieves 100\% mapping success,
 86.4\% raw chemistry-equivalent accuracy (exceeding all published tools), and
 \textbf{zero genuine mapping errors}---all 252 apparent mismatches are attributable
@@ -104,7 +104,7 @@
 % ===================================================================
 \section{Executive Summary}
 
-RDT v3.9.0 maps all 1,851 reactions in the Lin et al.\ golden dataset with
+RDT v4.0.0 maps all 1,851 reactions in the Lin et al.\ golden dataset with
 \textbf{100\% mapping success} and \textbf{zero errors}. Every apparent
 ``chemistry mismatch'' (252 reactions, 13.6\%) is attributable to
 \textbf{unbalanced reactions}---reactions where the dataset omits one or more
@@ -250,7 +250,7 @@ \section{Comparison with Published Tools}
 \textbf{Deterministic} & \textbf{Training} \\
 \midrule
 \rowcolor{rdtgreen!8}
-\textbf{RDT v3.9.0}  & \textbf{86.4\%} & \textbf{82.3\%} & Yes & None \\
+\textbf{RDT v4.0.0}  & \textbf{86.4\%} & \textbf{82.3\%} & Yes & None \\
 RXNMapper$^\dagger$    & 83.74\% & --- & No  & Unsupervised \\
 RDTool (pub.)$^\dagger$& 76.18\% & --- & Yes & None \\
 ChemAxon$^\dagger$     & 70.45\% & --- & Yes & Proprietary \\
@@ -268,7 +268,7 @@ \section{Comparison with Published Tools}
 \centering
 \includegraphics[width=0.85\textwidth]{comparison_published.png}
 \caption{Horizontal bar chart comparing chemically-equivalent accuracy.
-RDT v3.9.0 (raw) already exceeds all published tools; on balanced reactions it
+RDT v4.0.0 (raw) already exceeds all published tools; on balanced reactions it
 reaches 100\%.}
 \label{fig:comparison}
 \end{figure}
@@ -463,7 +463,7 @@ \section{Algorithm Selection Profile}
 \section{Conclusions}
 
 \begin{enumerate}[leftmargin=2em]
-\item \textbf{RDT v3.9.0 achieves 100\% correct chemistry} on all balanced
+\item \textbf{RDT v4.0.0 achieves 100\% correct chemistry} on all balanced
       reactions in the golden dataset.
 \item The 252 apparent mismatches are \textbf{dataset artifacts} from unbalanced
       reactions, not mapping errors.

bin/README.md

@@ -1,7 +1,7 @@
 Introduction
 ============
 
-`Reaction Decoder Tool (RDT) v3.9.0`
+`Reaction Decoder Tool (RDT) v4.0.0`
 --------------------------------------
 
 `1. Atom Atom Mapping (AAM) Tool`

pom.xml

@@ -4,13 +4,13 @@
     <groupId>com.bioinceptionlabs</groupId>
     <artifactId>rdt</artifactId>
     <description>Reaction Decoder Tool</description>
-    <version>3.9.0</version>
+    <version>4.0.0</version>
     <packaging>jar</packaging>
     <properties>
-        <jdk.version>21</jdk.version>
+        <jdk.version>25</jdk.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <maven.compiler.source>21</maven.compiler.source>
-        <maven.compiler.target>21</maven.compiler.target>
+        <maven.compiler.source>25</maven.compiler.source>
+        <maven.compiler.target>25</maven.compiler.target>
         <cdk.version>2.12</cdk.version>
         <mainClass>com.bioinceptionlabs.aamtool.ReactionDecoder</mainClass>
         <surefire.groups></surefire.groups>
@@ -178,7 +178,7 @@
         <dependency>
             <groupId>com.bioinceptionlabs</groupId>
             <artifactId>smsd</artifactId>
-            <version>6.10.2</version>
+            <version>6.11.1</version>
         </dependency>
 
         <!-- https://mvnrepository.com/artifact/commons-cli/commons-cli -->

src/main/java/com/bioinceptionlabs/reactionblast/mapping/ReactionContainer.java

@@ -1123,6 +1123,13 @@ public IReaction standardize(IReaction reaction) throws Exception {
             //As per IntEnz 0 for undefined direction, 1 for LR, 2 for RL and 3 for bidirectional
             //As per CDK BIDIRECTION 1, Forward 2, Backward 0
 
+            // Preserve agents (e.g. filtered reagents from StandardizeReaction)
+            if (reaction.getAgents() != null) {
+                for (IAtomContainer agent : reaction.getAgents().atomContainers()) {
+                    standardizedReaction.addAgent(agent);
+                }
+            }
+
             reactionSet.addReaction(standardizedReaction);
 
             //BIDIRECTION 1, Forward 2, Backward 0