aiida-alc-ins
Caveat: agentic coding
This package is an experiment in the use of agentic coding to accelerate development of research software infrastructure in the Ada Lovelace Centre at STFC. It fits into a wider project and software stack:
-
Python libraries Euphonic (phonon data import and Fourier interpolation); abinslib (INS intensity calculations); resins (neutron instrument resolution functions).
-
AiiDA This package wraps the Python stack into reproducible AiiDA workflows: each project is represented as a directed acyclic graph of calculation and data "nodes".
-
AiiDAlab User-friendly graphical interfaces to AiiDA, intended for deployment to facilities users. These are being developed simultaneously, coordinated through https://github.com/stfc/alc-ux .
The inner (AiiDA plugin) layer is boilerplate-heavy and should be a meticulous interface between our Python libraries and AiiDA, presenting useful workflows for opinionated user-interface work in AiiDAlab plugins. It was identified as a good candidate for agentic development, which can refer to the AiiDA documentation, existing plugins and the documentation/tests/implementation of the underlying Python libraries. It is not supposed to include new scientific decisions or give different results to other means of accessing those libraries.
Initially this was an exploration of the
aiida-pythonjob
execution model; most AiiDA calculation plugins use command-line
interfaces, but the nature of abinslib and resins makes it awkward
to maintain and expose all their development through consistent CLIs.
Initial results were promising and so this has become the preferred implementation route.
After an ad-hoc "PLAN.md" start, this is being developed in
"spec-driven" style using various LLMs with
openspec. The behaviour this package
guarantees is specified in openspec/specs/, and
some more human-friendly reasoning behind the design is recorded in
docs/source/design_notes.rst.
Installation
pip install aiida-alc-ins
The PyPI distribution is aiida-alc-ins, but the import package is still
aiida_pythonjob_ins until 0.2, when it is renamed to aiida_alc_ins.
Development setup
This project uses uv and Python 3.12.
uv sync # create .venv and install deps (+ dev group)
uv run pytest # run the test suite (parallel by default)
Test execution is parallel by default, using pytest-xdist to run
across all available CPU cores. The containerized integration tests
are xdist-safe use a file lock to coordinate a shared container across
workers (see conftest.py).
To run tests sequentially (e.g. for debugging or clearer tracebacks):
uv run pytest -n 0
What's implemented
- Custom data types:
ForceConstantsData,QpointPhononModesData,EuphonicCrystalData(wrap Euphonic objects via their public JSON round-trip, stored in the node repository).EuphonicCrystalDatabridges euphonic'sCrystalto/from AiiDA's nativeStructureData. - Native AiiDA types: the force constants' crystal is exposed as a
StructureData(no ASE dependency), from which aKpointsDataband path is built (also the input q-point specification for Fourier interpolation). Results map toBandsData(frequencies as bands), sobands.show_mpl()plots the phonon band structure with no AiiDALab dependency. - Atomic operations (plain public-API functions):
band_path_qpoints(seekpath; structure only),read_force_constants_from_castepandinterpolate_phonon_modes(plus acalculate_dispersionconvenience), andcalculate_tosca_spectrum(inelastic-neutron-scattering intensities viaabinslib+resins). The compute-heavy ops run asaiida-pythonjobPythonJobs. - Input formats: read force constants from CASTEP (
.castep_bin) or from Phonopy output (phonopy.yaml+FORCE_CONSTANTSorforce_constants.hdf5[+BORN]); read phonon modes from a EuphonicQpointPhononModesJSON dump. - Workflows starting from force constants (each takes a
force_constantsinput namespace holding exactly one source: a CASTEPcastep_file, aphonopynamespace ofsummary/force_constants/bornSinglefileData, or a preparedForceConstantsDataasnode):ForceConstantsWorkChainresolves that source into aForceConstantsData, reading CASTEP or Phonopy files in-process with acalcfunction. The workflows below run it as a sub-workflow, and it can also be launched on its own.DispersionWorkChainfollows it with threecalcfunctions (extract structure, build q-point path, composeBandsData) and an interpolationPythonJob, with full provenance.DosWorkChaincomputes a phonon density of states (Monkhorst-Pack sampling + adaptive broadening) as a nativeXyData.ToscaFromForceConstantsWorkChainsamples modes across the Brillouin zone and delegates toToscaFromModesWorkChainbelow, re-exposing its outputs.
- Workflows starting from phonon modes:
ToscaFromModesWorkChainsimulates the spectrum the TOSCA spectrometer would record: a PythonJob computes the full line set (per atom, quantum order and detector bank) as a nativeXyData, thencalcfunctions group and resolution-broaden it. Splitting the steps this way means regrouping reuses the cached intensity calculation.
Usage sketch
import matplotlib
from aiida import load_profile, orm
from aiida.engine import run_get_node
from aiida.plugins import WorkflowFactory
load_profile()
# Load plugins via standard AiiDA factories (direct imports like
# `from aiida_pythonjob_ins.workflows import DispersionWorkChain` also work)
DispersionWorkChain = WorkflowFactory("pythonjob_ins.dispersion")
# A Python `Code` on some computer (here: interpreter with euphonic installed).
code = orm.load_code("python3@localhost")
results, node = run_get_node(
DispersionWorkChain,
force_constants={
"castep_file": orm.SinglefileData("quartz.castep_bin"),
},
q_spacing=orm.Float(0.025),
code=code,
)
# The same workflow from Phonopy files, read in-process from the `phonopy` source
results, node = run_get_node(
DispersionWorkChain,
force_constants={
"phonopy": {
"summary": orm.SinglefileData("phonopy.yaml"),
"force_constants": orm.SinglefileData("force_constants.hdf5"),
},
},
q_spacing=orm.Float(0.025),
code=code,
)
results["band_path"] # KpointsData: q-point path + high-symmetry labels
results["band_structure"] # BandsData: phonon band structure
results["phonon_modes"] # QpointPhononModesData: frequencies + eigenvectors
# Plot with the native AiiDA/matplotlib tooling (no AiiDALab needed):
results["band_structure"].show_mpl()
# Or drop back to Euphonic objects when needed:
modes = results["phonon_modes"].get_modes() # euphonic.QpointPhononModes
spectrum = modes.get_dispersion() # euphonic.Spectrum1D
See tests/ for runnable examples using the official AiiDA pytest fixtures.
Documentation
Sphinx docs combine API reference (sphinx-autoapi) with a runnable tutorial
gallery (sphinx-gallery): each example executes a real AiiDA workflow, plots the
result, and visualises the provenance graph. Build them with:
uv run --group doc make -C docs html # needs system Graphviz + procps
Output lands in docs/build/html. The gallery runs in a throwaway in-memory AiiDA
profile, so it never touches your real ~/.aiida.
Logging
The atomic operations emit progress messages through the standard logging
module under the aiida_pythonjob_ins logger namespace. As a library, this
package only emits logs; it never installs handlers or sets levels, so you
control verbosity from your application:
import logging
# Show INFO-level messages from this package (basicConfig adds a stderr handler):
logging.basicConfig(level=logging.WARNING)
logging.getLogger("aiida_pythonjob_ins").setLevel(logging.INFO)
Use logging.DEBUG for more detail, or logging.WARNING (the effective default)
to silence progress messages. Because the package logger is separate from
AiiDA's own aiida logger, changing this level does not affect AiiDA's logging.
When an operation runs inside a PythonJob (a separate process), its stdout and
stderr are captured into the calculation's retrieved files. To have INFO logs
appear there, raise the level inside that process — e.g. via the code's
prepend_text, or AiiDA's logging configuration (verdi config set).
References
- Euphonic — docs, PyPI
abinslib— docs, PyPIresins— docs, PyPIaiida-pythonjob— docs- Writing AiiDA plugins and testing them
- AiiDA materials-science data types
- Related in-house effort: stfc/alc-ux
Metadata
Release files for aiida-alc-ins 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiida_alc_ins-0.1.0.tar.gz | 53.4 kB | With provenance | Details for aiida_alc_ins-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiida_alc_ins-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aiida_alc_ins-0.1.0-py3-none-any.whl |
Total release size: 109.9 kB
Release files / aiida_alc_ins-0.1.0.tar.gz
| Download URL | aiida_alc_ins-0.1.0.tar.gz |
|---|---|
| Size | 53.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
988087a35b239944e900096963f9380f1092c6c06cee0209f208e5ec5d1ef648
|
|
BLAKE2b-256 checksum How to use checksums |
f13321c82c89c17e59f176680fd5eb01b9c1d85a9e383d7f0777ce9b4c7fd7b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / aiida_alc_ins-0.1.0-py3-none-any.whl
| Download URL | aiida_alc_ins-0.1.0-py3-none-any.whl |
|---|---|
| Size | 56.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f2921d7648e85e9ace4d75edd03699ab7c28b4b8ca969fc48080246429d2114d
|
|
BLAKE2b-256 checksum How to use checksums |
4007bc7890ab8f11cbfb192f7bc5cb39517f26f3d7714f39bbf8d6eeae509748
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for aiida-alc-ins 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aiida_alc_ins-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.