Using ASE2SPRKKR
The SPRKKR calculator prepares and runs native SPR-KKR tasks from
ASE structures or existing potentials. If you have not yet run a
calculation, follow the First calculation: aluminium SCF and DOS first. For physics and
convergence settings, consult the
SPR-KKR manual.
Tasks and input parameters
The default task is SCF. Other tasks include DOS, ARPES,
SPLEED, BSFEK, BSFKK and JXC; some less established
tasks are marked experimental. Inspect the installed version to find
task names and available options:
ase2sprkkr info --task
ase2sprkkr info --task=SCF
ase2sprkkr info --task=SCF.ENERGY
A calculator can receive a task name, an input-file path or an
InputParameters object. For example:
from ase.build import bulk
from ase2sprkkr import InputParameters, SPRKKR
parameters = InputParameters.for_task("SCF")
parameters.ENERGY.NE = 5
atoms = bulk("Al", "fcc", a=4.05)
calculator = SPRKKR(atoms=atoms, input_parameters=parameters)
result = calculator.calculate()
print("SCF energy (eV):", result.energy)
print("Converged:", result.converged)
You can change an option on the calculator with
calculator.set({"ENERGY.NE": 6}), or override it for one run with
calculator.calculate(options={"ENERGY.NE": 6}).
A section-qualified name avoids ambiguity when different sections have
options with the same name.
Interactive parameter editing
Input-parameter defaults belong to the calculator and can be inspected and changed before running a task. For example:
from ase.build import bulk
from ase2sprkkr import SPRKKR
calculator = SPRKKR(atoms=bulk("Al", "fcc", a=4.05),
input_parameters="SCF")
calculator.set({"ENERGY.NE": 12})
print(calculator.get("ENERGY.NE"))
# The same option can be accessed through its section:
calculator.input_parameters.ENERGY.NE = 16
print(calculator.input_parameters.ENERGY.NE())
# This changes the option for just one calculation:
result = calculator.calculate(options={"ENERGY.NE": 24})
The calculator retains its default value of 16 after this one-time
override. To select a different task or replace all parameter defaults,
assign to calculator.input_parameters (for example, "DOS",
an InputParameters instance, or an input-file path). The
input_parameters argument to calculate() can also select
a task for a single calculation without replacing the defaults.
Use ase2sprkkr info --task=TASK to discover valid settings.
To inspect an existing SPR-KKR input file without running a calculation:
from ase2sprkkr import InputParameters
parameters = InputParameters.from_file("existing.inp")
print(parameters.task_name)
Incomplete files can be inspected with
InputParameters.from_file("existing.inp", allow_incomplete=True).
Input files do not contain all the physical data needed to run
a calculation; a potential or atoms must also be provided.
For task-definition internals and shared parameter schemas, see
ASE2SPRKKR architecture for developers.
Site occupations and symmetry
ASE structures can describe geometry, but SPR-KKR needs additional
site properties, including chemical occupations and atomic-type data.
promote_ase_atoms() adds the sites interface to an ASE
Atoms object. Promotion also happens when atoms are supplied to
the SPRKKR calculator.
Symmetry-equivalent sites can share a SiteType. To change
only one site, first call break_symmetry(); otherwise editing
a shared occupation raises an error:
from ase.build import bulk
from ase2sprkkr import promote_ase_atoms
atoms = promote_ase_atoms(
bulk("LiCl", "rocksalt", a=5.64) * (2, 1, 1)
)
site = atoms.sites[3] # one of the chlorine sites
site.break_symmetry()
site.occupation.set({"Cl": 0.5, "I": 0.5})
# Adding Br at 20% reduces the existing fractions proportionally:
site.occupation["Br"] = 0.2
print(site.occupation["Br"])
print(site.occupation.as_dict)
To modify all equivalent sites together, edit their shared
site.site_type.occupation instead of breaking symmetry.
Occupation values are normalized; atomic types can be specified by
their chemical symbols or atomic numbers. Changes are synchronized to
ASE’s atoms.info["occupancy"] representation using the
spacegroup_kinds mapping, and existing ASE occupancy metadata is
recognized when atoms are promoted.
Different occupation fractions represent chemical disorder (such as a substitutional alloy), not a larger explicitly ordered supercell. The consequences of changing equivalence or converting a disordered cell are discussed in Crystal symmetry and cell transformations.
Potentials and consecutive tasks
An SPR-KKR .pot file contains atomic-site information and the
electronic potential used by native calculations. It is not a
pseudopotential library such as VASP’s POTCAR.
Create a starting potential from an ASE structure, or load an existing one:
from ase.build import bulk
from ase2sprkkr import Potential
potential = Potential.from_atoms(bulk("Al", "fcc", a=4.05))
previous = Potential.from_file("existing.pot")
When starting from atoms, ASE2SPRKKR prepares a potential containing
the site information needed for the native calculation. When starting
from a previous .pot file, the stored electronic state can be
reused. Input parameters specify the task and its controls; they do
not replace the structure and electronic data in the potential.
For that reason, loading an .inp file alone is insufficient
unless its referenced potential can also be found.
A calculator owns default atoms or a potential, along with default
input parameters. Explicit atoms, potential and
input_parameters arguments to calculate() select the
physical state and task for that run. Do not supply both an Atoms
object and a Potential object to the calculator constructor;
the latter already contains the atomic structure. During preparation,
input parameters are copied before per-run options and generated paths
are inserted, but atoms and potential objects are mutable working
state: promoting atoms, adding empty spheres, or synchronizing the
potential may modify them. Once prepared, a run uses its own
materialized files.
A converged SCF potential can be used for a subsequent DOS calculation:
from ase.build import bulk
from ase2sprkkr import SPRKKR
scf = SPRKKR(atoms=bulk("Al", "fcc", a=4.05)).calculate()
if not scf.converged:
raise RuntimeError("SCF did not converge")
dos = SPRKKR(input_parameters="DOS").calculate(
potential=scf.potential_filename
)
print(dos.dos_filename)
Passing the potential explicitly identifies which SCF run supplies it. Alternatively, the SCF result provides a calculator associated with the new potential, suitable for the next task:
dos = scf.calculator.calculate(input_parameters="DOS")
A successful synchronous SCF calculation can also update the
original calculator’s potential when it uses that calculator’s
default physical state. If a run overrides its atoms or potential,
do not assume those one-time changes have become calculator defaults.
Use the result’s potential or scf.calculator to choose the
state explicitly.
For the full first-calculation walkthrough, see First calculation: aluminium SCF and DOS. For more examples of calculations beyond SCF and DOS, see the ASE2SPRKKR paper (Eddhib et al., 2026) and Examples by application.
To generate native input files without executing SPR-KKR:
from ase.build import bulk
from ase2sprkkr import SPRKKR
SPRKKR(atoms=bulk("Al", "fcc", a=4.05)).save_input(
input_file="example.inp", potential_file="example.pot"
)
save_input() returns the prepared input parameters and the paths
of the input, potential and output files. The destination directory
must be persistent; directory=False is only for actual runs
using create_run() or calculate().
Filename templates
The calculator’s input_file, potential_file and
output_file names can contain placeholders that are resolved
while preparing a calculation:
Placeholder |
Replacement |
|---|---|
|
Chemical symbols / structure label derived from the atoms |
|
Task name, as supplied and in uppercase respectively |
|
Calculator label (empty if none was supplied) |
|
Local date and time (format |
|
Incrementing calculation counter |
|
Underscore separator: omitted at the start of a filename;
consecutive |
For example:
calculator = SPRKKR(
atoms=bulk("Al", "fcc", a=4.05),
label="test",
input_file="%l%_%a_%T.inp",
potential_file="%a.pot",
)
_, input_name, potential_name, _ = calculator.save_input()
print(input_name, potential_name)
The values are resolved consistently for each prepared calculation,
including when multiple filenames use the same placeholder.
The %d format contains a colon, which is not portable in
Windows filenames; choose another template there.
Inspecting SCF results
The SCF result contains parsed iterations, convergence information and access to the newly written potential. After a calculation:
scf = SPRKKR(atoms=bulk("Al", "fcc", a=4.05)).calculate()
print("Iterations:", len(scf.iterations))
print("Converged:", scf.converged)
print("Final convergence error:", scf.last_iteration.error())
print("Final spin moment:", scf.last_iteration.moment.spin())
print("Total energies:", scf.iterations.values_of(("energy", "ETOT")))
print("Output potential:", scf.potential_filename)
print("Charge data:", scf.potential.CHARGE())
The iteration data can be used to monitor convergence or to
postprocess many calculations. The final error and magnetic
moments come from the native output; whether the result is physically
converged must be checked separately from successful process
completion. Plotting the error history (with the optional plot
dependencies installed) is also possible through
scf.plot("error").
Results and further workflows
calculate() returns a task-specific TaskResult, including
parsed quantities and paths to output files. You can also read
recognized result files independently:
from ase2sprkkr import ResultFile
dos_data = ResultFile.from_file("calculation.dos")
See Result files, plots and NeXus export for plotting, Grace files and NeXus export, Remote running, MPI and execution profiles for MPI and execution profiles, and Persistent project calculations for persistent calculations and reconnection. Command-line commands are collected in Command-line reference, with runnable examples in Examples by application.