Onça-pintada
Onça-pintada is a Python package designed to compute thermodynamic properties of binary and multicomponent alloys. It enables the calculation of enthalpy, entropy, and Gibbs free energy of mixing within the subregular solution model, as well as the determination of binodal and spinodal curves for phase diagrams.
The package also supports the evaluation of cluster interactions using the quasi-chemical approximation (QCA), allowing for the description of chemical short-range order (CSRO). Additionally, it provides tools to reconstruct atomistic geometries of alloys based on short-range order metrics, facilitating subsequent calculations of their electronic properties.
The Cluster Expansion builder follows Calango Studio's native approach: it decorates an active sublattice, groups pair/triplet/quadruplet clusters by distance, and retains configurations with distinct correlation fingerprints. It supports exact compositions and seeded sampling for binary and multicomponent alloys, with pure end members preserved during unrestricted generation. The SQS module optimizes fixed-composition supercells against random-alloy correlations using simulated annealing, including periodic pair and optional triplet/quadruplet clusters. No ICET dependency is required.
Installation
python -m pip install oncapintada
For development from a local checkout (Python 3.10 or later):
python -m pip install -e '.[dev,docs]'
python -m pytest
Getting started
import numpy as np
from ase.build import bulk
from oncapintada import BinaryAlloy, ClusterExpansionOptions, generate_cluster_expansion
alloy = BinaryAlloy([[-3.0, -3.9], [-3.1, -4.0]], dilution=0.1)
x = np.linspace(0, 1, 101)
gibbs = alloy.gibbs_free_energy_of_mixing(x, [300, 600]) # kJ/mol
parent = bulk("Cu", "fcc", a=3.6, cubic=True)
options = ClusterExpansionOptions(
active_element="Cu",
species=("Cu", "Au", "Ag"),
supercell=(2, 1, 1),
pair_cutoff=2.7,
composition=(0.5, 0.25, 0.25),
seed=42,
)
result = generate_cluster_expansion(parent, options)
result.write("CuAuAg.extxyz")
print(len(result.configs), result.exhaustive)
See the quick start, Cluster Expansion guide, SQS guide, Monte Carlo guide, review notes, and runnable binary/ternary example.
Fingerprint equality means correlation equivalence at the selected cutoffs,
not proven space-group symmetry equivalence. Degeneracies are exact only when
result.exhaustive is true. A ridge energy fit with held-out validation is
available through fit_effective_cluster_interactions; compute consistent
energies for the generated configurations before fitting.
Imports are silent. Use oncapintada.banner() when environment diagnostics are
needed. Random alloy, Cluster Expansion, and SQS generation are supported
structure workflows. ASE-backed Metropolis chains support species swaps, random
displacements, and optional geometry relaxation.
SQS supercells
from oncapintada import generate_sqs
# The same API handles binary and multicomponent alloys.
for name, composition in {
"CuAu": {"Cu": 0.5, "Au": 0.5},
"CuAuAg": {"Cu": 0.5, "Au": 0.25, "Ag": 0.25},
}.items():
sqs = generate_sqs(
parent,
composition,
supercell=(2, 2, 2), # 32 atoms for this conventional FCC parent
pair_cutoff=3.7, # first two FCC neighbor shells, in Å
n_steps=10_000,
seed=42,
)
sqs.write(f"{name}_sqs.extxyz")
print(name, sqs.species_counts, sqs.objective, sqs.converged)
Inspect the correlation mismatch before using the structure for calculator runs. Targets use the composition actually realized after site-count rounding. Annealing returns the best visited decoration; it does not guarantee a globally optimal SQS. See examples/sqs.py for an executable workflow.
Energy-based Monte Carlo
from ase.calculators.emt import EMT
from oncapintada import MetropolisMonteCarlo
mc = MetropolisMonteCarlo(
sqs.atoms, calculator=EMT, temperature=600,
move="mixed", distribution="gaussian", displacement=0.03,
swap_indices=sqs.active_indices, seed=42,
)
chain = mc.run(100)
chain.write("mc_trajectory.extxyz")
print(chain.energy, chain.best_energy, chain.acceptance_rate)
Moves either exchange two unlike species or independently displace all atoms.
Metropolis acceptance uses total calculator energies in eV and temperature in
kelvin. Add relax=True, optimizer="BFGS" to optimize each proposal before
comparing energies; this performs a basin-hopping structure search. See the
executable example and
Monte Carlo guide for relaxation and diagnostics.
Use a temperature schedule for simulated annealing:
from oncapintada import TemperatureSchedule
cooling = TemperatureSchedule(1200, 100, n_steps=1000, scheme="exponential")
annealer = MetropolisMonteCarlo(sqs.atoms, calculator=EMT, temperature=cooling)
annealed = annealer.run(1000)
print(annealed.temperatures, annealed.best_energy)
Schedules include constant, linear, exponential, and regularized inverse-log
cooling (scheme="logarithmic"). They advance on attempted proposals,
including rejections, and continue across successive run() calls. A callable
temperature law is also supported. All temperatures are in kelvin.
License
This is open source code under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for oncapintada 26.10.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| oncapintada-26.10.2.tar.gz | 6.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| oncapintada-26.10.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.0 MB
Release files / oncapintada-26.10.2.tar.gz
| Download URL | oncapintada-26.10.2.tar.gz |
|---|---|
| Size | 6.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9334c775aa54e8e8d0285e11acffa62a92dbe2276b2dba224d79763e5bb681d
|
|
BLAKE2b-256 checksum How to use checksums |
a8ca027bc59ae89388e508106e0fde1f725d96c2778ebe53e3bdbde0cdee15cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / oncapintada-26.10.2-py3-none-any.whl
| Download URL | oncapintada-26.10.2-py3-none-any.whl |
|---|---|
| Size | 58.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f625a596e3fc87c78962fb275954b0120d15bb6adb663151999aea1a0b5848c
|
|
BLAKE2b-256 checksum How to use checksums |
d5b788dafea27c1fae89fcf6a83edaf3ace5090d7385be2b9f3de2995c7f7781
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
