Added support for multi-structure inputs.

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [unreleased]
 
+### Added
+
+- `ProgramInput.structures` and `DualProgramInput.structures` for additional named structures required by calculations with multiple complete structure inputs, while keeping `.structure` as the required primary/start/reference structure. [#103](https://github.com/coltonbh/qcdata/pull/103) by [@coltonbh](https://github.com/coltonbh).
+
 ## [0.17.1] - 2026-04-21
 
 ### Added

docs/api/inputs.md

@@ -2,6 +2,8 @@ Data structures for specifying quantum chemistry calculations. The most commonly
 
 A `DualProgramInput` is used when two inputs are required for a calculation. For example, doing a geometry optimization with `geomeTRIC` while using a `subprogram` like `TeraChem` or `Psi4` to compute the gradients.
 
+`ProgramInput.structure` is always the primary/start/reference structure for the calculation. Calculations that require additional complete structures can provide them by role name with `ProgramInput.structures`, for example `structures={"product": product_structure}` for a nudged elastic band calculation where `structure` is the reactant endpoint. Calculation-specific tools should validate which structure names are required.
+
 A `FileInput` is an escape hatch that allows you to run _any_ calculation in any QC program (or any program for that matter), even if it isn't a supported [`CalcType`](./calctype.md) in `qcdata` yet. You can use a `FileInput` to store the native input files (text and binary) for a QC program along with the relevant command line args. Using [qcop](https://github.com/coltonbh/qcop) you can submit a `FileInput` to a QC program and all output files and `logs` produced by that program will be collected and returned in a user-friendly [`ProgramOutput`](./outputs.md) object. `FileInput` allows you to continue to use `qcdata` even for calculations that haven't yet been standardized.
 
 

src/qcdata/models/inputs.py

@@ -58,9 +58,13 @@ class _StructureKeywordsMixin(_KeywordsMixin):
     """
     Attributes:
         structure: The structure to be used in the calculation.
+        structures: Additional named structures required by the calculation. The
+            primary/start/reference structure should remain in `structure`; this field
+            is for other complete structures such as a product endpoint in NEB.
     """
 
     structure: Structure
+    structures: dict[str, Structure] = {}
 
     def __init__(self, **data: Any):
         """Backwards compatibility for 'molecule' attribute."""
@@ -156,6 +160,8 @@ class ProgramInput(ProgramArgs, _StructureKeywordsMixin):
         keywords Dict[str, Any]: A dict of keywords to be passed to the program
             excluding model and calctype. Defaults to an empty dict.
         structure Structure: The structure to be used in the calculation.
+        structures Dict[str, Structure]: Additional named structures required by the
+            calculation. Defaults to an empty dict.
         files Files: Files to be passed to the QC program.
         extras Dict[str, Any]: Additional information to bundle with the object. Use
             for schema development and scratch space.
@@ -165,12 +171,14 @@ class ProgramInput(ProgramArgs, _StructureKeywordsMixin):
         from qcdata.models import ProgramInput, Structure
 
         struct = Structure.open("path/to/structure.xyz")
+        product_struct = Structure.open("path/to/product_structure.xyz")
 
         prog_inp = ProgramInput(
             calctype = "energy",
             structure = struct,
             model = {"method": "hf", "basis": "6-31G"},
             keywords = {"maxsteps": "250"},  # Optional
+            structures = {"product": product_struct},  # Optional
             files = {"file1": b"binary data"}  # Optional
         )
         ```
@@ -193,6 +201,8 @@ class DualProgramInput(ProgramArgsSub, ProgramInput):
         keywords Dict[str, Any]: A dict of keywords to be passed to the program
             excluding model and calctype. Defaults to an empty dict.
         structure Structure: The structure to be used in the calculation.
+        structures Dict[str, Structure]: Additional named structures required by the
+            calculation. Defaults to an empty dict.
         files Files: Files to be passed to the QC program.
         subprogram: The name of the subprogram to use.
         subprogram_args ProgramArgs: The ProgramArgs for the subprogram.