Special Quasirandom Structures¶

Optional dependency

SqsGenerator requires the sqsgen extra.

uvpip

uv add "materialsframework[sqsgen]"

pip install "materialsframework[sqsgen]"

SqsGenerator ¶

SqsGenerator(
    iterations: int = 1000,
    make_structures: bool = True,
    mode: Literal["random", "systematic"] = "random",
    structure_format: str = "pymatgen",
    log_level: Literal[
        "trace", "debug", "info", "warning", "error"
    ] = "warning",
)

A class used to generate Special Quasirandom Structures (SQS).

Generates structures that approximate a random arrangement of atoms while matching specific pair and multi-site correlation functions.

Initializes the SqsGenerator object.

Parameters:

Name	Type	Description	Default
`iterations`	`int`	The number of iterations for the SQS generation. Defaults to 1000.	`1000`
`make_structures`	`bool`	Whether to generate the structures during the optimization process. Defaults to True.	`True`
`mode`	`Literal['random', 'systematic']`	The mode for SQS generation. Defaults to "random".	`'random'`
`structure_format`	`str`	The structure format for the generated SQS structure. Defaults to "pymatgen".	`'pymatgen'`
`log_level`	`Literal['trace', 'debug', 'info', 'warning', 'error']`	The log level for the SQS generation. Defaults to "warning".	`'warning'`

generate ¶

generate(
    composition: Composition | str,
    crystal_structure: str = "FCC",
    supercell_size: tuple[int, int, int] = (5, 5, 5),
    shell_weights: dict[int, float] | None = None,
) -> dict[str, Any]

Generates a supercell using the SQS (Special Quasirandom Structures) method.

Parameters:

Name	Type	Description	Default
`composition`	`Composition \| str`	The composition of the supercell.	required
`crystal_structure`	`str`	The crystal structure of the supercell. Defaults to "FCC".	`'FCC'`
`supercell_size`	`tuple[int, int, int]`	The size of the supercell. Defaults to (5, 5, 5).	`(5, 5, 5)`
`shell_weights`	`dict[int, float]`	The weights for the coordination shells. Defaults to {1: 1.0, 2: 0.5}.	`None`

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: Dictionary with keys: - `structure`: Generated SQS structure. - `objective`: Final objective value from SQS optimization.

Raises:

Type	Description
`ValueError`	If the crystal structure is invalid.