Skip to main content

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). EuphonicCrystalData bridges euphonic's Crystal to/from AiiDA's native StructureData.
  • Native AiiDA types: the force constants' crystal is exposed as a StructureData (no ASE dependency), from which a KpointsData band path is built (also the input q-point specification for Fourier interpolation). Results map to BandsData (frequencies as bands), so bands.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_castep and interpolate_phonon_modes (plus a calculate_dispersion convenience), and calculate_tosca_spectrum (inelastic-neutron-scattering intensities via abinslib + resins). The compute-heavy ops run as aiida-pythonjob PythonJobs.
  • Input formats: read force constants from CASTEP (.castep_bin) or from Phonopy output (phonopy.yaml + FORCE_CONSTANTS or force_constants.hdf5 [+ BORN]); read phonon modes from a Euphonic QpointPhononModes JSON dump.
  • Workflows starting from force constants (each takes a force_constants input namespace holding exactly one source: a CASTEP castep_file, a phonopy namespace of summary/force_constants/born SinglefileData, or a prepared ForceConstantsData as node):
    • ForceConstantsWorkChain resolves that source into a ForceConstantsData, reading CASTEP or Phonopy files in-process with a calcfunction. The workflows below run it as a sub-workflow, and it can also be launched on its own.
    • DispersionWorkChain follows it with three calcfunctions (extract structure, build q-point path, compose BandsData) and an interpolation PythonJob, with full provenance.
    • DosWorkChain computes a phonon density of states (Monkhorst-Pack sampling + adaptive broadening) as a native XyData.
    • ToscaFromForceConstantsWorkChain samples modes across the Brillouin zone and delegates to ToscaFromModesWorkChain below, re-exposing its outputs.
  • Workflows starting from phonon modes:
    • ToscaFromModesWorkChain simulates the spectrum the TOSCA spectrometer would record: a PythonJob computes the full line set (per atom, quantum order and detector bank) as a native XyData, then calcfunctions 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

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)

Source distribution for aiida-alc-ins 0.1.0
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)

Table of built distributions (wheels) for aiida-alc-ins 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page