[reference_energies] add atomic reference energy solvers

Implement ReferenceEnergies helpers for regression- and
reference-compound-based atomic energy estimation, including
fixed-species constraints, provenance metadata, tests, and docs.

Author: alexurba

docs/source/api/index.rst

@@ -6,6 +6,7 @@ This section provides detailed API documentation for the aenet-python package.
 .. toctree::
    :maxdepth: 2
 
+   reference_energies
    trainset
    transformations
    torch_featurize
@@ -14,6 +15,13 @@ This section provides detailed API documentation for the aenet-python package.
    torch_training_training
    torch_training_inference
 
+Reference Energies
+------------------
+
+:doc:`reference_energies`
+   Helper API for constructing atomic reference energies from regression and
+   other supported workflows.
+
 Training Set Management
 -----------------------
 

docs/source/api/reference_energies.rst

@@ -0,0 +1,24 @@
+.. _api_reference_energies:
+
+Reference Energies
+==================
+
+The ``aenet.reference_energies`` module provides helper routines for
+constructing atomic reference energies used in cohesive- and
+formation-energy-based workflows.
+
+Both `ReferenceEnergies.from_regression()` and
+`ReferenceEnergies.from_reference_compounds()` consume lightweight
+``(composition, energy)`` samples directly, so callers can stream data from
+custom parsers without materializing full structure objects. For file-backed
+workflows, the module also provides a lazy helper that yields those samples
+from paths readable by ``aenet.io.structure``.
+
+.. currentmodule:: aenet.reference_energies
+
+.. autoclass:: ReferenceEnergies
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autofunction:: iter_composition_energy_samples_from_files

docs/source/usage/torch_training.rst

@@ -44,6 +44,15 @@ dataset-backed prediction, and committee training, see
 `example-05-torch-training.ipynb
 <https://github.com/atomisticnet/aenet-python/blob/master/notebooks/example-05-torch-training.ipynb>`_.
 
+If you need to construct ``atomic_energies`` programmatically before
+training or before building a large HDF5 dataset, see
+:class:`aenet.reference_energies.ReferenceEnergies`. Its regression helper
+accepts lazy ``(composition, energy)`` samples directly, and its
+reference-compound helper selects the lowest-energy sample for each requested
+composition before solving the constrained system. The module also provides a
+file-path iterator backed by ``aenet.io.structure`` for streaming-friendly
+preprocessing.
+
 
 Energy-Only Training
 --------------------