Class Assembly

optimade/models/structures.py:217–274

A description of groups of sites that are statistically correlated. - **Examples** (for each entry of the assemblies list): - `{"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.

class Assembly(BaseModel):
    """A description of groups of sites that are statistically correlated.

    - **Examples** (for each entry of the assemblies list):
        - `{"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.
          Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.
        - `{"sites_in_groups": [[1,2], [3]], "group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.
          The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site.
          30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).

    """

    sites_in_groups: Annotated[
        list[list[int]],
        OptimadeField(
            description="""Index of the sites (0-based) that belong to each group for each assembly.

- **Examples**:
    - `[[1], [2]]`: two groups, one with the second site, one with the third.
    - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.""",
            support=SupportLevel.MUST,
            queryable=SupportLevel.OPTIONAL,
        ),
    ]

    group_probabilities: Annotated[
        list[float],
        OptimadeField(
            description="""Statistical probability of each group. It MUST have the same length as `sites_in_groups`.
It SHOULD sum to one.
See below for examples of how to specify the probability of the occurrence of a vacancy.
The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.""",
            support=SupportLevel.MUST,
            queryable=SupportLevel.OPTIONAL,
        ),
    ]

    @field_validator("sites_in_groups", mode="after")
    @classmethod
    def validate_sites_in_groups(cls, value: list[list[int]]) -> list[list[int]]:
        sites = []
        for group in value:
            sites.extend(group)
        if len(set(sites)) != len(sites):
            raise ValueError(
                f"A site MUST NOT appear in more than one group. Given value: {value}"
            )
        return value

    @model_validator(mode="after")
    def check_self_consistency(self) -> "Assembly":
        if len(self.group_probabilities) != len(self.sites_in_groups):
            raise ValueError(
                f"sites_in_groups and group_probabilities MUST be of same length, "
                f"but are {len(self.sites_in_groups)} and {len(self.group_probabilities)}, "
                "respectively"
            )
        return self