create base structure for energies (#91)

* transfered changes from 28 to new structure

* ruff

* reorg energy and force structure

* updated outputs list

* added default tests for energies forces and thermodynamics

* removed mechanics

* expanded thermodynamics

* ruff

* updated to BaseModelMethod for contribution ref

* standardized normalization function syntax

* more normalization functions

* fixed error

* improved descriptions, addressed most other review items

* ruff

* fixed import, remove value descriptions

---------

Co-authored-by: jrudz <[email protected]>

src/nomad_simulations/schema_packages/outputs.py

@@ -16,6 +16,7 @@
 # limitations under the License.
 #
 
+import numpy as np
 from typing import TYPE_CHECKING, List, Optional
 
 from nomad.datamodel.data import ArchiveSection
@@ -43,6 +44,11 @@
     HoppingMatrix,
     Permittivity,
     XASSpectrum,
+    TotalEnergy,
+    KineticEnergy,
+    PotentialEnergy,
+    TotalForce,
+    Temperature,
 )
 
 
@@ -70,7 +76,8 @@ class Outputs(ArchiveSection):
     model_method_ref = Quantity(
         type=ModelMethod,
         description="""
-        Reference to the `ModelMethod` section in which the output physical properties were calculated.
+        Reference to the `ModelMethod` section containing the details of the mathematical
+        model with which the output physical properties were calculated.
         """,
         a_eln=ELNAnnotation(component='ReferenceEditQuantity'),
     )
@@ -111,6 +118,16 @@ class Outputs(ArchiveSection):
 
     xas_spectra = SubSection(sub_section=XASSpectrum.m_def, repeats=True)
 
+    total_energy = SubSection(sub_section=TotalEnergy.m_def, repeats=True)
+
+    kinetic_energy = SubSection(sub_section=KineticEnergy.m_def, repeats=True)
+
+    potential_energy = SubSection(sub_section=PotentialEnergy.m_def, repeats=True)
+
+    total_force = SubSection(sub_section=TotalForce.m_def, repeats=True)
+
+    temperature = SubSection(sub_section=Temperature.m_def, repeats=True)
+
     # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
     # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 
@@ -310,3 +327,50 @@ def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
                     physical_property=phys_property,
                     logger=logger,
                 )
+
+
+class WorkflowOutputs(Outputs):
+    """
+    This section contains output properties that depend on a single system, but were
+    calculated as part of a workflow (e.g., the energies from a geometry optimization),
+    and thus may include step information.
+    """
+
+    step = Quantity(
+        type=np.int32,
+        description="""
+        The step number with respect to the workflow.
+        """,
+    )
+
+    # TODO add this in when we link to nomad-simulations-workflow schema
+    # ? check potential circular imports problems when the nomad-simulations-workflow schema is transferred here
+    # workflow_ref = Quantity(
+    #     type=SimulationWorkflow,
+    #     description="""
+    #     Reference to the `SelfConsistency` section that defines the numerical settings to converge the
+    #     output property.
+    #     """,
+    # )
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)
+
+
+class TrajectoryOutputs(WorkflowOutputs):
+    """
+    This section contains output properties that depend on a single system, but were
+    calculated as part of a trajectory (e.g., temperatures from a molecular dynamics
+    simulation), and thus may include time information.
+    """
+
+    time = Quantity(
+        type=np.float64,
+        unit='ps',
+        description="""
+        The elapsed simulated physical time since the start of the trajectory.
+        """,
+    )
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)

src/nomad_simulations/schema_packages/physical_property.py

@@ -24,6 +24,7 @@
 from nomad import utils
 from nomad.datamodel.data import ArchiveSection
 from nomad.datamodel.metainfo.basesections import Entity
+from nomad.datamodel.metainfo.annotations import ELNAnnotation
 from nomad.metainfo import (
     URL,
     MEnum,
@@ -41,6 +42,7 @@
 
 from nomad_simulations.schema_packages.numerical_settings import SelfConsistency
 from nomad_simulations.schema_packages.variables import Variables
+from nomad_simulations.schema_packages.model_method import BaseModelMethod
 
 # We add `logger` for the `validate_quantity_wrt_value` decorator
 logger = utils.get_logger(__name__)
@@ -324,3 +326,27 @@ def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
 
         # Resolve if the physical property `is_derived` or not from another physical property.
         self.is_derived = self._is_derived()
+
+
+class PropertyContribution(PhysicalProperty):
+    """
+    Abstract physical property section linking a property contribution to a contribution
+    from some method.
+
+    Abstract class for incorporating specific contributions of a physical property, while
+    linking this contribution to a specific component (of class `BaseModelMethod`) of the
+    over `ModelMethod` using the `model_method_ref` quantity.
+    """
+
+    model_method_ref = Quantity(
+        type=BaseModelMethod,
+        description="""
+        Reference to the `ModelMethod` section to which the property is linked to.
+        """,
+        a_eln=ELNAnnotation(component='ReferenceEditQuantity'),
+    )
+
+    def normalize(self, archive, logger) -> None:
+        super().normalize(archive, logger)
+        if not self.name:
+            self.name = self.get('model_method_ref').get('name')

src/nomad_simulations/schema_packages/properties/__init__.py

@@ -18,7 +18,31 @@
 
 from .band_gap import ElectronicBandGap
 from .band_structure import ElectronicBandStructure, ElectronicEigenvalues
-from .energies import ChemicalPotential, FermiLevel
+from .energies import (
+    FermiLevel,
+    EnergyContribution,
+    TotalEnergy,
+    KineticEnergy,
+    PotentialEnergy,
+)
+from .forces import BaseForce, ForceContribution, TotalForce
+from .thermodynamics import (
+    Pressure,
+    Volume,
+    Temperature,
+    Heat,
+    Work,
+    InternalEnergy,
+    Enthalpy,
+    Entropy,
+    GibbsFreeEnergy,
+    HelmholtzFreeEnergy,
+    ChemicalPotential,
+    HeatCapacity,
+    VirialTensor,
+    MassDensity,
+    Hessian,
+)
 from .fermi_surface import FermiSurface
 from .hopping_matrix import CrystalFieldSplitting, HoppingMatrix
 from .permittivity import Permittivity

src/nomad_simulations/schema_packages/properties/energies.py

@@ -20,33 +20,76 @@
 
 import numpy as np
 
-from nomad.metainfo import Quantity
+from nomad.metainfo import Quantity, Section, Context, SubSection
 
 if TYPE_CHECKING:
     from nomad.metainfo import Section, Context
     from nomad.datamodel.datamodel import EntryArchive
     from structlog.stdlib import BoundLogger
 
-from nomad_simulations.schema_packages.physical_property import PhysicalProperty
+from nomad_simulations.schema_packages.physical_property import (
+    PhysicalProperty,
+    PropertyContribution,
+)
 
+##################
+# Abstract classes
+##################
 
-class FermiLevel(PhysicalProperty):
+
+class BaseEnergy(PhysicalProperty):
     """
-    Energy required to add or extract a charge from a material at zero temperature. It can be also defined as the chemical potential at zero temperature.
+    Abstract class used to define a common `value` quantity with the appropriate units
+    for different types of energies, which avoids repeating the definitions for each
+    energy class.
     """
 
-    # ! implement `iri` and `rank` as part of `m_def = Section()`
-
-    iri = 'http://fairmat-nfdi.eu/taxonomy/FermiLevel'
-
     value = Quantity(
         type=np.float64,
         unit='joule',
         description="""
-        The value of the Fermi level.
         """,
     )
 
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)
+
+
+class EnergyContribution(BaseEnergy, PropertyContribution):
+    """
+    Abstract class for incorporating specific energy contributions to the `TotalEnergy`.
+    The inheritance from `PropertyContribution` allows to link this contribution to a
+    specific component (of class `BaseModelMethod`) of the over `ModelMethod` using the
+    `model_method_ref` quantity.
+
+    For example, for a force field calculation, the `model_method_ref` may point to a
+    particular potential type (e.g., a Lennard-Jones potential between atom types X and Y),
+    while for a DFT calculation, it may point to a particular electronic interaction term
+    (e.g., 'XC' for the exchange-correlation term, or 'Hartree' for the Hartree term).
+    Then, the contribution will be named according to this model component and the `value`
+    quantity will contain the energy contribution from this component evaluated over all
+    relevant atoms or electrons or as a function of them.
+    """
+
+    # TODO address the dual parent normalization explicity
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)
+
+
+####################################
+# List of specific energy properties
+####################################
+
+
+class FermiLevel(BaseEnergy):
+    """
+    Energy required to add or extract a charge from a material at zero temperature. It can be also defined as the chemical potential at zero temperature.
+    """
+
+    # ! implement `iri` and `rank` as part of `m_def = Section()`
+
+    iri = 'http://fairmat-nfdi.eu/taxonomy/FermiLevel'
+
     def __init__(
         self, m_def: 'Section' = None, m_context: 'Context' = None, **kwargs
     ) -> None:
@@ -58,29 +101,41 @@ def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
         super().normalize(archive, logger)
 
 
-class ChemicalPotential(PhysicalProperty):
+#! The only issue with this structure is that total energy will never be a sum of its contributions,
+#! since kinetic energy lives separately, but I think maybe this is ok?
+class TotalEnergy(BaseEnergy):
     """
-    Free energy cost of adding or extracting a particle from a thermodynamic system.
+    The total energy of a system. `contributions` specify individual energetic
+    contributions to the `TotalEnergy`.
     """
 
-    # ! implement `iri` and `rank` as part of `m_def = Section()`
-
-    iri = 'http://fairmat-nfdi.eu/taxonomy/ChemicalPotential'
-
-    value = Quantity(
-        type=np.float64,
-        unit='joule',
-        description="""
-        The value of the chemical potential.
-        """,
-    )
+    # ? add a generic contributions quantity to PhysicalProperty
+    contributions = SubSection(sub_section=EnergyContribution.m_def, repeats=True)
 
     def __init__(
         self, m_def: 'Section' = None, m_context: 'Context' = None, **kwargs
     ) -> None:
         super().__init__(m_def, m_context, **kwargs)
-        self.rank = []
         self.name = self.m_def.name
 
     def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
         super().normalize(archive, logger)
+
+
+# ? Separate quantities for nuclear and electronic KEs?
+class KineticEnergy(BaseEnergy):
+    """
+    Physical property section describing the kinetic energy of a (sub)system.
+    """
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)
+
+
+class PotentialEnergy(BaseEnergy):
+    """
+    Physical property section describing the potential energy of a (sub)system.
+    """
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)