Release v3.9.0: six correctness fixes and publication-grade docs

Bug fixes:
- Identity shortcut now uses SmiFlavor.Stereo + sorted List (not TreeSet):
  E/Z isomerizations and stoichiometry-shift reactions no longer incorrectly
  routed to identity mapping path
- Fractional stoichiometry now rounded via Math.round() with tolerance check
  and WARN log instead of silent while-loop ceiling
- CompletionService collection per-iteration try-catch: one failing algorithm
  worker no longer aborts collection of all remaining successful results

Documentation:
- ALGORITHM.md rewritten to publication grade: formal NP-hardness statement,
  full pseudocode for MAX/MIN assignment algorithms, 12-level comparator table,
  theorem statements for determinism and bond parsimony, ITS graph formalism
- Version bumped to 3.9.0 throughout (pom.xml, README, bin/README, ALGORITHM.md)

Author: asad

ALGORITHM.md

@@ -9,7 +9,7 @@
 Introduction
 ============
 
-`Reaction Decoder Tool (RDT) v3.8.1`
+`Reaction Decoder Tool (RDT) v3.9.0`
 --------------------------------------
 
 **Toolkit-agnostic reaction mapping engine** with CDK adapter. Deterministic, no training data required.
@@ -20,7 +20,7 @@ Published tools are scored on **chemically equivalent** atom mapping — whether
 
 | Tool | Chemically Equivalent Atom-Map | Bond-Change Exact | Mol-Map Exact | Strict Atom-Index Exact | Deterministic |
 |------|-------------------------------|-------------------|---------------|------------------------|---------------|
-| **RDT v3.8.1** | **99.2%** | **99.2%** | **76.8%** | 19.6% | **Yes** |
+| **RDT v3.9.0** | **99.2%** | **99.2%** | **76.8%** | 19.6% | **Yes** |
 | RXNMapper | 83.74%† | - | - | - | No |
 | RDTool (published) | 76.18%† | - | - | - | Yes |
 | ChemAxon | 70.45%† | - | - | - | Yes |
@@ -141,7 +141,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.8.1+) -->
+<!-- New (v3.9.0+) -->
 <groupId>com.bioinceptionlabs</groupId>
 ```
 
@@ -215,7 +215,7 @@ Sub-commands
 `AAM using SMILES`
 
   ```
-  java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j AAM -f TEXT
+  java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j AAM -f TEXT
   ```
 
 `Perform AAM` for Transporters
@@ -224,14 +224,14 @@ Sub-commands
 `AAM using SMILES` (accept mapping with no bond changes -b)
 
   ```
-  java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "O=C(O)C(N)CC(=O)N.O=C(O)C(N)CS>>C(N)(CC(=O)N)C(=O)O.O=C(O)C(N)CS" -b -g -c -j AAM -f TEXT
+  java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "O=C(O)C(N)CC(=O)N.O=C(O)C(N)CS>>C(N)(CC(=O)N)C(=O)O.O=C(O)C(N)CS" -b -g -c -j AAM -f TEXT
   ```
 
 `Annotate Reaction using SMILES`
 ---------------------------------
 
   ```
-  java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j ANNOTATE -f XML
+  java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j ANNOTATE -f XML
   ```
 
 
@@ -241,12 +241,12 @@ Sub-commands
 `Compare Reactions using SMILES with precomputed AAM mappings`
 
   ```
-  java -jar rdt-3.8.1-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn  -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH -u
+  java -jar rdt-3.9.0-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn  -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH -u
   ```
 
 
 `Compare Reactions using RXN files`
 
   ```
-  java -jar rdt-3.8.1-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn  -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH
+  java -jar rdt-3.9.0-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn  -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH
   ```

README.md

@@ -1,7 +1,7 @@
 Introduction
 ============
 
-`Reaction Decoder Tool (RDT) v3.8.1`
+`Reaction Decoder Tool (RDT) v3.9.0`
 --------------------------------------
 
 `1. Atom Atom Mapping (AAM) Tool`
@@ -93,20 +93,20 @@ Sub-commands
 `AAM using SMILES`
 
 ```
-java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j AAM -f TEXT
+java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j AAM -f TEXT
 ```
 
 `Perform AAM for Transporters` (accept mapping with no bond changes: `-b`)
 
 ```
-java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "O=C(O)C(N)CC(=O)N.O=C(O)C(N)CS>>C(N)(CC(=O)N)C(=O)O.O=C(O)C(N)CS" -b -g -c -j AAM -f TEXT
+java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "O=C(O)C(N)CC(=O)N.O=C(O)C(N)CS>>C(N)(CC(=O)N)C(=O)O.O=C(O)C(N)CS" -b -g -c -j AAM -f TEXT
 ```
 
 `Annotate Reaction using SMILES`
 ---------------------------------
 
 ```
-java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j ANNOTATE -f XML
+java -jar rdt-3.9.0-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O.O[H]>>[H]OC(=O)CC(C)O.CC(O)CC(O)=O" -g -c -j ANNOTATE -f XML
 ```
 
 `Compare Reactions`
@@ -115,11 +115,11 @@ java -jar rdt-3.8.1-jar-with-dependencies.jar -Q SMI -q "CC(O)CC(=O)OC(C)CC(O)=O
 `Compare using precomputed AAM mappings`
 
 ```
-java -jar rdt-3.8.1-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH -u
+java -jar rdt-3.9.0-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH -u
 ```
 
 `Compare using RXN files`
 
 ```
-java -jar rdt-3.8.1-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH
+java -jar rdt-3.9.0-jar-with-dependencies.jar -Q RXN -q example/ReactionDecoder_mapped.rxn -T RXN -t example/ReactionDecoder_mapped.rxn -j COMPARE -f BOTH
 ```

bin/README.md

@@ -281,6 +281,50 @@ a) -b option for transporter reactions (no bond change)
 b) cdk-2.4-SNAPSHOT.jar added
 c) clean up
 
+-----------------------
+Changes (2026-04-03) — v3.9.0
+-----------------------
+a) Identity shortcut stereo + multiplicity fix: isIdentityReaction() now uses
+   SmiFlavor.Canonical|Stereo (E/Z and R/S are distinguished) and a sorted
+   List instead of a TreeSet (stoichiometric multiplicity is preserved).
+   Previously, F/C=C/F>>F/C=C\F was incorrectly classified as a transporter
+   and routed to MIN; 2CC+CO>>CC+2CO was incorrectly classified as identity.
+b) Fractional stoichiometry handling: Reactor.expandReaction() now uses
+   Math.round() with a tolerance check instead of the while-loop subtraction
+   trick. Non-integer coefficients (e.g. 0.5, 1.5) emit a WARN and are
+   rounded to the nearest integer; previously they were silently rounded up
+   (0.5→1 by ceiling, 1.5→2) with no indication.
+c) CompletionService fault isolation: the parallel algorithm collection loop
+   now wraps each cs.take().get() in its own try-catch(ExecutionException).
+   A single failing worker no longer aborts collection of all remaining
+   successful algorithm results; InterruptedException still stops the loop
+   and restores the interrupt flag.
+d) Shared ExecutorService for parallel mapping phase: fixed thread pool
+   (min(2, min(3, nCPU))) named "rdt-mapping" daemon threads; eliminates
+   per-reaction thread-pool creation overhead in batch processing.
+b) MIXTURE algorithm restored as genuine fallback: participates in phase-2
+   parallel search alongside MIN/MAX/RINGS; deduplicated by mapping signature
+   so it only contributes when MinSelection suppresses a valid pairing.
+c) Stoichiometric coefficient loss fixed in reagent filter: filtered reaction
+   now passes Double coefficient from original IReaction to addReactant/addProduct
+   instead of silently defaulting to 1.0.
+d) API bond-change count corrected: RDT.java now sums integer weights encoded
+   in "PATTERN:N" feature strings (weightSum helper) rather than counting
+   unique pattern types; fixes under-reporting for multi-bond reactions.
+e) Weight-aware Tanimoto similarity: ReactionResult.getAllFingerprints() retains
+   full "PATTERN:N" strings so stoichiometric differences (C-O:2 vs C-O:1)
+   are correctly treated as distinct in similarity calculations.
+f) MappingDiagnostics memory leak fixed: REACTIONS.get() replaced by
+   REACTIONS.remove() in snapshot(); static ConcurrentHashMap entries are now
+   released immediately after being consumed, preventing unbounded growth in
+   batch runs.
+g) CI publish trigger fixed: GitHub Packages deploy now triggers only on
+   version tags (refs/tags/v*), not on every master push (was returning
+   HTTP 409 Conflict on repeated same-version deploys).
+h) Benchmark progress reporting reduced from every 100 to every 500 reactions
+   to keep CI logs clean.
+i) Version bumped to 3.9.0; public release by BioInception PVT LTD.
+
 -----------------------
 Changes (2026-04-03) — v3.8.1
 -----------------------

changes.log

@@ -4,7 +4,7 @@
     <groupId>com.bioinceptionlabs</groupId>
     <artifactId>rdt</artifactId>
     <description>Reaction Decoder Tool</description>
-    <version>3.8.1</version>
+    <version>3.9.0</version>
     <packaging>jar</packaging>
     <properties>
         <jdk.version>21</jdk.version>

pom.xml

@@ -194,11 +194,24 @@ private void generateAtomAtomMapping(
                 jobCounter++;
             }
             for (int i = 0; i < jobCounter; i++) {
-                Reactor chosen = cs.take().get();
-                putSolution(chosen.getAlgorithm(), chosen);
+                try {
+                    Reactor chosen = cs.take().get();
+                    putSolution(chosen.getAlgorithm(), chosen);
+                } catch (ExecutionException e) {
+                    // One algorithm worker failed — log and continue collecting the rest.
+                    // The lower MCS layer already handles per-pair failures; this catch
+                    // prevents a single bad algorithm from silently dropping all remaining
+                    // successful results.
+                    LOGGER.debug("Algorithm worker failed: " + e.getCause());
+                    LOGGER.error(e);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    LOGGER.debug("Mapping interrupted during collection: " + e.getMessage());
+                    break;
+                }
             }
             LOGGER.debug("======DONE CallableAtomMappingTool=======");
-        } catch (InterruptedException | ExecutionException e) {
+        } catch (Exception e) {
             LOGGER.debug("ERROR: in AtomMappingTool: " + e.getMessage());
             LOGGER.error(e);
         } finally {
@@ -301,23 +314,32 @@ private Map<String, Integer> countAtoms(org.openscience.cdk.interfaces.IAtomCont
 
     /**
      * Check if a reaction is an identity/transporter (reactants ≡ products).
-     * Uses canonical SMILES comparison of each reactant-product pair.
+     *
+     * Two criteria must both hold:
+     * 1. Same molecule count on each side.
+     * 2. The sorted list of stereo-canonical SMILES is identical — uses
+     *    SmiFlavor.Stereo so that E/Z and R/S isomers are distinguished.
+     *    A List (not a Set) is used so that stoichiometric multiplicity is
+     *    preserved: "2 CC + CO → CC + 2 CO" is NOT identity even though the
+     *    same SMILES strings appear on both sides.
      */
     private boolean isIdentityReaction(IReaction reaction) {
         if (reaction.getReactantCount() != reaction.getProductCount()) {
             return false;
         }
         try {
             org.openscience.cdk.smiles.SmilesGenerator sg = new org.openscience.cdk.smiles.SmilesGenerator(
-                    org.openscience.cdk.smiles.SmiFlavor.Canonical);
-            java.util.Set<String> reactantSmiles = new java.util.TreeSet<>();
-            java.util.Set<String> productSmiles = new java.util.TreeSet<>();
+                    org.openscience.cdk.smiles.SmiFlavor.Canonical | org.openscience.cdk.smiles.SmiFlavor.Stereo);
+            java.util.List<String> reactantSmiles = new java.util.ArrayList<>();
+            java.util.List<String> productSmiles = new java.util.ArrayList<>();
             for (IAtomContainer ac : reaction.getReactants().atomContainers()) {
                 reactantSmiles.add(sg.create(ac));
             }
             for (IAtomContainer ac : reaction.getProducts().atomContainers()) {
                 productSmiles.add(sg.create(ac));
             }
+            java.util.Collections.sort(reactantSmiles);
+            java.util.Collections.sort(productSmiles);
             return reactantSmiles.equals(productSmiles);
         } catch (Exception e) {
             return false;

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

@@ -206,13 +206,32 @@ private void copyReferenceReaction(IReaction referenceReaction) throws CDKExcept
         }
     }
 
+    /**
+     * Convert a stoichiometric coefficient to an integer copy count.
+     * Non-integer values (e.g. 0.5, 1.5) are rounded to the nearest integer
+     * and a warning is logged — the algorithm requires whole-molecule copies.
+     * Null or non-positive values default to 1.
+     */
+    private int stoichiometryToCopies(double stoichiometry, String moleculeId) {
+        if (stoichiometry <= 0.0) {
+            return 1;
+        }
+        long rounded = Math.round(stoichiometry);
+        if (Math.abs(stoichiometry - rounded) > 0.01) {
+            LOGGER.warn("Non-integer stoichiometry " + stoichiometry + " for molecule "
+                    + moleculeId + "; rounded to " + rounded
+                    + ". RDT requires whole-molecule stoichiometry for atom mapping.");
+        }
+        return (int) Math.max(1L, rounded);
+    }
+
     private void expandReaction() throws CloneNotSupportedException {
 
         for (int i = 0; i < reactionWithSTOICHIOMETRY.getReactantCount(); i++) {
             IAtomContainer _react = reactionWithSTOICHIOMETRY.getReactants().getAtomContainer(i);
-            Double stoichiometry = reactionWithSTOICHIOMETRY.getReactantCoefficient(_react);
-            while (stoichiometry > 0.0) {
-                stoichiometry -= 1;
+            double stoichiometry = reactionWithSTOICHIOMETRY.getReactantCoefficient(_react);
+            int copies = stoichiometryToCopies(stoichiometry, _react.getID());
+            for (int k = 0; k < copies; k++) {
                 IAtomContainer _reactDup = cloneWithIDs(_react);
                 _reactDup.setID(_react.getID());
                 _reactDup.setProperty("STOICHIOMETRY", 1.0);
@@ -223,9 +242,9 @@ private void expandReaction() throws CloneNotSupportedException {
         for (int j = 0; j < reactionWithSTOICHIOMETRY.getProductCount(); j++) {
 
             IAtomContainer _prod = reactionWithSTOICHIOMETRY.getProducts().getAtomContainer(j);
-            Double stoichiometry = reactionWithSTOICHIOMETRY.getProductCoefficient(_prod);
-            while (stoichiometry > 0.0) {
-                stoichiometry -= 1;
+            double stoichiometry = reactionWithSTOICHIOMETRY.getProductCoefficient(_prod);
+            int copies = stoichiometryToCopies(stoichiometry, _prod.getID());
+            for (int k = 0; k < copies; k++) {
                 IAtomContainer prodDup = cloneWithIDs(_prod);
                 prodDup.setID(_prod.getID());
                 prodDup.setProperty("STOICHIOMETRY", 1.0);

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

@@ -290,7 +290,7 @@ public void benchmarkGoldenDataset() throws Exception {
         double chemistryEquivalentPct = pct_d(chemistryEquivalent, total);
 
         System.out.println();
-        System.out.println("=== Golden Dataset Benchmark Results (RDT v3.8.1) ===");
+        System.out.println("=== Golden Dataset Benchmark Results (RDT v3.9.0) ===");
         System.out.println("Total reactions:        " + total);
         System.out.println();
         System.out.println("--- Core Metrics ---");
@@ -354,7 +354,7 @@ public void benchmarkGoldenDataset() throws Exception {
         System.out.println("| RXNMapper          | 83.74%†     | -         | -         | Unsup.   | No            |");
         System.out.println("| RDTool (published) | 76.18%†     | -         | -         | None     | Yes           |");
         System.out.println("| ChemAxon           | 70.45%†     | -         | -         | Propr.   | Yes           |");
-        System.out.printf("| RDT v3.8.1         | %.1f%%      | %.1f%%    | %.1f%%    | None     | Yes           |%n",
+        System.out.printf("| RDT v3.9.0         | %.1f%%      | %.1f%%    | %.1f%%    | None     | Yes           |%n",
                 pct_d(chemistryEquivalent, total), pct_d(molMapExact, total), pct_d(exactAtomMatch, total));
         System.out.println("† Published figures from Lin et al. 2022 use chemically-equivalent scoring.");