PhaseForge

Optional dependency

Sqs2tdb requires the calphad extra, plus the sqs2tdb binary (part of ATAT) on PATH, with its SQS database configured via ~/.atat.rc.

uvpip

uv add "materialsframework[calphad]"

pip install "materialsframework[calphad]"

Sqs2tdb

Sqs2tdb(
    md_temperature: float = 1000,
    md_pressure: float = 1,
    md_timestep: float = 1.0,
    md_scaling_matrix: int = 2,
    fmax: float = 0.001,
    verbose: bool = False,
    calculator: BaseCalculator | None = None,
)

Python wrapper for the sqs2tdb script.

Attributes:

Name	Type	Description
dbf	Database	The TDB database object.

References

• ATAT sqs2tdb: https://doi.org/10.1016/j.calphad.2017.05.005

Initialize the wrapper with the path to the sqs2tdb script.

Parameters:

Name	Type	Description	Default
md_temperature	float	The temperature for MD calculations. Defaults to 1000 K.	1000
md_pressure	float	The pressure for MD calculations. Defaults to 1 atm.	1
md_timestep	float	The timestep for MD calculations. Defaults to 1 fs.	1.0
md_scaling_matrix	int	The supercell scaling matrix applied to the 'LIQUID' lattice before running MD. Defaults to 2 (a 2x2x2 supercell).	2
fmax	float	The maximum force tolerance for relaxation. Defaults to 0.001 eV/A.	0.001
verbose	bool	Whether to print verbose output. Defaults to False.	False
calculator	BaseCalculator | None	The calculator object used for energy calculations. Must also be a BaseMDCalculator if the 'LIQUID' lattice will be fit. Defaults to a lazily constructed default calculator.	None

Raises:

Type	Description
EnvironmentError	If the sqs2tdb script is not found in the system's PATH.

available_lattices property

available_lattices: list[str]

Get the list of available lattice types in the ATAT SQS database.

Returns:

Type	Description
list[str]	List[str]: The list of available lattice types.

calculator property

calculator: BaseCalculator

Returns the calculator instance used for energy, force, and stress calculations.

If the calculator instance is not already initialized, this method returns the default calculator.

Returns:

Name	Type	Description
BaseCalculator	BaseCalculator	The calculator object used for energy, force, and stress calculations.

fit

fit(
    species: list[str],
    lattices: list[str] | None = None,
    level: int = 1,
    t_min: float = 298.15,
    t_max: float = 10000,
    sro: bool = False,
    bv: float = 0.005,
    phonon: bool = False,
    open_calphad: bool = False,
    terms: str
    | list[tuple[int, int]]
    | dict[str, str | list[tuple[int, int]]]
    | None = None,
) -> None

Copy SQS from the database to the current directory, calculate energies, and fit a TDB model.

Parameters:

Name	Type	Description	Default
species	list	List of elements to consider (e.g., ["Al", "Ni"]).	required
lattices	List[str] | None	The lattice types (e.g., ["FCC_A1", "BCC_A2"]). Defaults to all available lattices in the ATAT SQS database.	None
level	int	The composition mesh level (e.g., 1 for midpoints). Defaults to 1.	1
t_min	float	The minimum temperature for fitting. Defaults to 298.15 K.	298.15
t_max	float	The maximum temperature for fitting. Defaults to 10000 K.	10000
sro	bool	Whether to include short-range order. Defaults to False.	False
bv	float	The energy bump value. Defaults to 5e-3.	0.005
phonon	bool	Whether to include phonons for end members. Defaults to False.	False
open_calphad	bool	Whether to generate an Open Calphad-compliant .tdb file. Defaults to False.	False
terms	str | list[tuple[int, int]] | dict[str, ...] | None	The terms.in content used to fit each lattice's solution model. Each (order, level) pair becomes one line of ATAT's terms.in format (order: 1 linear-in-composition, 2 binary interaction, 3 ternary, etc.; level: the polynomial degree of that interaction). Accepts: - None (default): use the built-in per-lattice default. - A single string (raw terms.in content) or a list of (order, level) pairs: applied to every lattice being fit. - A dict keyed by lattice name (e.g. {"BCC_A2": [(1, 0), (2, 0)]}), each value being either form above: applied per lattice, with any lattice not listed falling back to the built-in default.	None

Raises:

Type	Description
ValueError	If the calculator object does not implement the required properties.
ValueError	If the lattice type is not valid.
ValueError	If "LIQUID" is among the requested lattices but the calculator does not support MD.
ValueError	If terms is a dict containing a key that is not among the lattices being fit.