Merge branch 'develop' into physical-property-tweaking

Author: ndaelman-hu

docs/general.md

@@ -110,3 +110,56 @@ class SUPERCODEParser:
         # append `Simulation` as an `archive.data` section
         archive.data.append(simulation)
 ```
+
+## Homogenization and the role of Workflows
+
+Workflows are a device for annotating the structure of a set of entries in a standardized way.
+A community can define a workflow schema, i.e. its standout sections, without any knowledge of the underlying entries.
+As such, workflows define a homogenized data format with rich semantics that act as the starting point wherefrom to explore the dataset.
+The actual workflow entry instance, meanwhile, handles the coordination between tasks and the underlying data.
+This mapping may be a mixture of (workflow) entries and sections.
+
+Below are a few examples of actual mappings.
+Important to note is that these examples already presuppose a certain structure on the side of the referenced `archive.data` sections.
+In reality, workflow should be capable of hosting multiple underlying structures.
+
+### Serial Updates to `ModelSystem`
+
+Geometry optimizations or molecular dynamics simulations, for example, typically store their data in a single entry.
+Tasks trace the updates to the system, i.e. calculation or time steps, respectively.
+The actual modifications of these steps are stored in the `model_system` and `outputs`.
+<!-- @JFRudzinski pls double-check the order of the arrows -->
+
+```
+entry_x#workflow2.task[0].input  -> entry_y1#data.model_system[0]
+entry_x#workflow2.task[0].output -> entry_y2#data.outputs[0]
+...
+entry_x#workflow2.task[n].input  -> entry_y1#data.model_system[n]
+entry_x#workflow2.task[n].output -> entry_y2#data.outputs[n]
+```
+
+Note that `entry_x`, `entry_y1`, `entry_y2` will typically refer to the same entry, though this isn't a hard requirement.
+
+#### Including SCF steps
+
+!!! warning "Under construction"
+    This section will be updated once its schema-side is settled on.
+
+### Single-Point SCF Workflow
+
+In the case of a single-point calculation, the emphasis clearly lies on the relaxation of the electronic structure.
+Now, each `outputs` section can wholesale be dedicated to following the SCF cycle.
+
+```
+entry_x#workflow2.task[0].output -> entry_y#data.outputs[0]
+```
+
+### Multi-step Electronic Workflows
+
+There are two main design choices here:
+
+1. the methodology and computed outputs are split along major subroutines.
+2. they are kept in a single entry. This is especially useful for legacy cases, where some subroutines were originally not distinguished.
+
+In option 2, for any workflows at are not simply _serial_, there is no canonical way of ordering `outputs`.
+This burden remains with `workflow2.tasks`.

src/nomad_simulations/schema_packages/atoms_state.py

@@ -551,7 +551,12 @@ class ParticleState(Entity):
     This can be extended to include any common quantities in the future.
     """
 
-    pass
+    label = Quantity(
+        type=str,
+        description="""
+        User- or program-package-defined identifier for this particle.
+        """,
+    )
 
 
 class AtomsState(ParticleState):
@@ -660,5 +665,83 @@ def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
             self.atomic_number = self.resolve_atomic_number(logger=logger)
 
 
-class CoarseGrainedState(ParticleState):
-    pass
+class CGBeadState(ParticleState):
+    """
+    A section to define coarse-grained bead state information.
+    """
+
+    # ? What do we want to qualify as type identifier? What safety checks do we need?
+    bead_symbol = Quantity(
+        type=str,
+        description="""
+        Symbol(s) describing the (base) CG particle type. Equivalent to chemical_symbol
+        for atomic elements.
+        """,
+    )
+
+    label = Quantity(
+        type=str,
+        description="""
+        User- or program-package-defined identifier for this bead site.
+        This could be used to store primary FF labels in cases where only a
+        secondary specification is required. Otherwise, `alt_labels` are
+        used to document more complex bead identifiers, e.g., bead interactions based
+        on connectivity.
+        """,
+    )
+
+    alt_labels = Quantity(
+        type=str,
+        shape=['*'],
+        description="""
+        A list of bead labels for multifaceted bead characterization.
+        """,
+    )
+
+    mass = Quantity(
+        type=np.float64,
+        unit='kg',
+        description="""
+        Total mass of the particle.
+        """,
+    )
+
+    charge = Quantity(
+        type=np.float64,
+        unit='coulomb',
+        description="""
+        Total charge of the particle.
+        """,
+    )
+
+    # Other possible quantities
+    #     diameter: float
+    #         The diameter of each particle.
+    #         Default: 1.0
+    #     body: int
+    #         The composite body associated with each particle. The value -1
+    #         indicates no body.
+    #         Default: -1
+    #     moment_inertia: float
+    #         The moment_inertia of each particle (I_xx, I_yy, I_zz).
+    #         This inertia tensor is diagonal in the body frame of the particle.
+    #         The default value is for point particles.
+    #         Default: 0, 0, 0
+    #     scaled_positions: list of scaled-positions #! for cell if relevant
+    #         Like positions, but given in units of the unit cell.
+    #         Can not be set at the same time as positions.
+    #         Default: 0, 0, 0
+    #     orientation: float
+    #         The orientation of each particle. In scalar + vector notation,
+    #         this is (r, a_x, a_y, a_z), where the quaternion is q = r + a_xi + a_yj + a_zk.
+    #         A unit quaternion has the property: sqrt(r^2 + a_x^2 + a_y^2 + a_z^2) = 1.
+    #         Default: 0, 0, 0, 0
+    #     angmom: float #? for cell or here?
+    #         The angular momentum of each particle as a quaternion.
+    #         Default: 0, 0, 0, 0
+    #     image: int #! advance PBC stuff would go in cell I guess
+    #         The number of times each particle has wrapped around the box (i_x, i_y, i_z).
+    #         Default: 0, 0, 0
+
+    def normalize(self, archive: 'EntryArchive', logger: 'BoundLogger') -> None:
+        super().normalize(archive, logger)