Skip to content

Helpers

assign_composition_formula_ids(assemblies, *, order=None)

Assign composition formula strings as IDs to the given assemblies.

Parameters:

Name Type Description Default
assemblies Iterable[Assembly]

The assemblies to assign IDs to.

 required
order Sequence[str] | None

The order of component kinds in the formula (e.g., ['M', 'L', 'X']). If None, kinds are sorted alphabetically. Default is None.

 None

Returns:

Type Description
list[Assembly]

Assemblies with composition formula strings as IDs (e.g., 'M1L2X2'). If multiple assemblies share the same formula, a numeric suffix is appended (e.g., 'M1L1X1-1').

Examples:

>>> from nasap_net import assign_composition_formula_ids
>>> indexed = assign_composition_formula_ids(
...     assemblies, order=['M', 'L', 'X']
... )
Source code in src/nasap_net/helpers/assembly_indexing.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def assign_composition_formula_ids(
        assemblies: Iterable[Assembly],
        *,
        order: Sequence[str] | None = None,
) -> list[Assembly]:
    """Assign composition formula strings as IDs to the given assemblies.

    Parameters
    ----------
    assemblies : Iterable[Assembly]
        The assemblies to assign IDs to.
    order : Sequence[str] | None, optional
        The order of component kinds in the formula (e.g., ``['M', 'L', 'X']``).
        If None, kinds are sorted alphabetically. Default is None.

    Returns
    -------
    list[Assembly]
        Assemblies with composition formula strings as IDs
        (e.g., ``'M1L2X2'``). If multiple assemblies share the same
        formula, a numeric suffix is appended (e.g., ``'M1L1X1-1'``).

    Examples
    --------
    >>> from nasap_net import assign_composition_formula_ids
    >>> indexed = assign_composition_formula_ids(
    ...     assemblies, order=['M', 'L', 'X']
    ... )
    """
    assigned_assemblies = [
        assembly.copy_with(
            id_=generate_composition_formula(assembly, order=order)
        )
        for assembly in assemblies
    ]
    return deduplicate_ids(assigned_assemblies)  # type: ignore