aiida_alc_ins.pythonjobs

AiiDA process wrappers around the atomic Euphonic operations.

We use aiida-pythonjob to run the plain functions in aiida_alc_ins.operations as AiiDA PythonJob processes. PythonJob runs through a Code on a Computer (localhost in tests, but any configured machine in production), so the standard AiiDA Computer/Code hooks apply. See https://github.com/aiidateam/aiida-pythonjob .

Code-environment note: aiida-pythonjob cloudpickles these module-level functions by reference – a tiny module+name string per job – so the remote unpickles via from aiida_alc_ins.operations import .... That module’s import chain is deliberately AiiDA-free, so loading the function on the remote does not import or initialise aiida (no profile/config needed there). By-reference pickling is the required execution strategy: scientific dependencies like Euphonic, NumPy, and seekpath contain compiled C-extensions that cannot be pickled by value. See “Remote Execution, Pickling, and register_pickle_by_value” in docs/source/design_notes.rst.

Functions

band_path_qpoints(→ QpointPath)

Return a QpointPath (q-points + labels + cell) for a band path.

calculate_dispersion(→ euphonic.QpointPhononModes)

Convenience: build a band path and interpolate modes along it.

calculate_dos(→ euphonic.Spectrum1D)

Compute a phonon density of states by sampling a Monkhorst-Pack grid.

calculate_tosca_spectrum(→ euphonic.Spectrum1DCollection)

Compute the full, ungrouped TOSCA intensity line set from phonon modes.

interpolate_phonon_modes(→ euphonic.QpointPhononModes)

Fourier-interpolate phonon modes at the given fractional q-points.

interpolate_phonon_modes_on_grid(...)

Interpolate phonon modes on a Monkhorst-Pack grid (a powder average).

read_force_constants_from_castep(→ euphonic.ForceConstants)

Read a CASTEP .castep_bin/.check file into ForceConstants.

read_force_constants_from_phonopy(...)

Read Phonopy output files into ForceConstants.

prepare_interpolation_inputs(→ dict[str, Any])

Build inputs to run interpolate_phonon_modes() as a PythonJob.

prepare_read_force_constants_inputs(→ dict[str, Any])

Build inputs to run read_force_constants_from_castep() as a PythonJob.

prepare_read_phonopy_inputs(→ dict[str, Any])

Build inputs to run read_force_constants_from_phonopy() as a PythonJob.

prepare_dispersion_inputs(→ dict[str, Any])

Build the input dict to run calculate_dispersion() as a PythonJob.

prepare_dos_inputs(→ dict[str, Any])

Build inputs to run calculate_dos() as a PythonJob.

prepare_grid_interpolation_inputs(→ dict[str, Any])

Build inputs to run interpolate_phonon_modes_on_grid() as a PythonJob.

prepare_tosca_spectrum_inputs(→ dict[str, Any])

Build inputs to run calculate_tosca_spectrum() as a PythonJob.

Module Contents

aiida_alc_ins.pythonjobs.band_path_qpoints(cell: tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], q_spacing: float = 0.025, *, insert_gamma: bool = True) → QpointPath[source]

Return a QpointPath (q-points + labels + cell) for a band path.

cell is a spglib-style (lattice, scaled_positions, numbers) tuple – e.g. from euphonic.Crystal.to_spglib_cell() or an ASE Atoms. Only the structure is needed; force constants are not. Pure/AiiDA-free: the parent-side generate_band_path calcfunction wraps this into a native KpointsData.

aiida_alc_ins.pythonjobs.calculate_dispersion(force_constants: euphonic.ForceConstants, q_spacing: float = 0.025, *, insert_gamma: bool = True, asr: str | None = 'reciprocal') → euphonic.QpointPhononModes[source]

Convenience: build a band path and interpolate modes along it.

aiida_alc_ins.pythonjobs.calculate_dos(force_constants: euphonic.ForceConstants, q_spacing: float = 0.1, energy_spacing: float = 1.0, *, energy_unit: str = 'meV', adaptive: bool = True, asr: str | None = 'reciprocal') → euphonic.Spectrum1D[source]

Compute a phonon density of states by sampling a Monkhorst-Pack grid.

Parameters

force_constants

Interatomic force constants to interpolate from.

q_spacing

Target spacing of the sampling grid, in 1/Angstrom (finer -> denser grid).

energy_spacing

Width of the DOS energy bins, in energy_unit.

energy_unit

Unit for the energy axis (e.g. "meV", "1/cm").

adaptive

Use adaptive broadening (per-mode widths from mode gradients) rather than fixed bins. Recommended; requires computing mode gradients.

asr

Acoustic sum rule applied during interpolation (None to disable).

Returns

Spectrum1D

Density of states vs energy (bin edges in x_data, values in y_data; use get_bin_centres() for matching x/y lengths).

aiida_alc_ins.pythonjobs.calculate_tosca_spectrum(modes: euphonic.QpointPhononModes, temperature: float = 10.0, energy_spacing: float = 10.0, energy_max: float = 4000.0, detector_angles: list[float] | None = None, final_energy: float = 32.0, energy_unit: str = '1/cm') → euphonic.Spectrum1DCollection[source]

Compute the full, ungrouped TOSCA intensity line set from phonon modes.

Combines fundamental (one-phonon) and combination (two-phonon) intensities in the almost-isotropic incoherent approximation, for every requested detector bank, into a single collection with one line per atom, quantum order and detector angle – mirroring the reference pipeline’s fundamentals + second_order sum, repeated per bank.

Cross-section weighting is applied explicitly via apply_weights to the raw (fundamentals + combinations) collection before grouping, producing physical intensities in cross-section-weighted units (barn * cm or barn / energy).

Parameters

modes

Phonon frequencies and eigenvectors (e.g. from a molecular-crystal calculation; the almost-isotropic approximation assumes hydrogenous, largely incoherent scattering).

temperature

Sample temperature in kelvin, governing the Debye-Waller attenuation.

energy_spacing, energy_max

Energy axis bin width and instrument-range cutoff, in energy_unit. See tosca_energy_bins().

detector_angles

Scattering angles in degrees, one per detector bank to evaluate. Defaults to TOSCA’s backward (135°) and forward (45°) banks.

final_energy

Analyser-fixed final neutron energy, in energy_unit.

energy_unit

Unit for energy_spacing, energy_max and final_energy. TOSCA results are conventionally reported in wavenumbers.

Returns

Spectrum1DCollection

One line per (atom, quantum order, detector angle), each carrying that triple in its line_data metadata under atom_symbol, quantum_order and detector_angle. Intensities are cross-section weighted with units of barn * cm (or barn / energy). Not yet grouped or broadened.

aiida_alc_ins.pythonjobs.interpolate_phonon_modes(force_constants: euphonic.ForceConstants, qpoints: numpy.ndarray, *, asr: str | None = 'reciprocal') → euphonic.QpointPhononModes[source]

Fourier-interpolate phonon modes at the given fractional q-points.

qpoints is an (N, 3) array in the crystal’s reciprocal basis (as provided by an AiiDA KpointsData). This is the core ForceConstants -> QpointPhononModes step.

aiida_alc_ins.pythonjobs.interpolate_phonon_modes_on_grid(force_constants: euphonic.ForceConstants, q_spacing: float = 0.1, *, asr: str | None = 'reciprocal') → euphonic.QpointPhononModes[source]

Interpolate phonon modes on a Monkhorst-Pack grid (a powder average).

Unlike interpolate_phonon_modes(), which evaluates a caller-supplied set of q-points (e.g. a high-symmetry band path), this samples the whole Brillouin zone the way calculate_dos() does – the sampling ToscaFromForceConstantsWorkChain needs. The almost-isotropic incoherent approximation disregards actual q-point positions (see the reference pipeline’s kinematic treatment in calculate_tosca_spectrum()), but still needs a representative density of modes across the zone, exactly as a DOS does.

Parameters

force_constants

Interatomic force constants to interpolate from.

q_spacing

Target spacing of the sampling grid, in 1/Angstrom (finer -> denser grid).

asr

Acoustic sum rule applied during interpolation (None to disable).

aiida_alc_ins.pythonjobs.read_force_constants_from_castep(filename: str | pathlib.Path) → euphonic.ForceConstants[source]

Read a CASTEP .castep_bin/.check file into ForceConstants.

A thin wrapper over ForceConstants.from_castep. It exists because a PythonJob’s function must be a plain module-level function: a bound classmethod (ForceConstants.from_castep) is a method, not a FunctionType, so aiida-pythonjob’s build_function_data rejects it. The wrapper is also where we attach logging.

filename is resolved relative to the working directory. When run as a PythonJob the CASTEP file is staged there via upload_files (see aiida_alc_ins.pythonjobs.prepare_read_force_constants_inputs()).

aiida_alc_ins.pythonjobs.read_force_constants_from_phonopy(summary_name: str = 'phonopy.yaml', fc_name: str = 'FORCE_CONSTANTS', born_name: str | None = None) → euphonic.ForceConstants[source]

Read Phonopy output files into ForceConstants.

Thin wrapper over ForceConstants.from_phonopy. Relative file names are joined to the current working directory (absolute names are used as given). As a PythonJob, aiida_alc_ins.pythonjobs.prepare_read_phonopy_inputs() stages the files there under the names it passes. Both are likely to be removed before version 1.0. Pass born_name=None to skip Born charges.

aiida_alc_ins.pythonjobs.prepare_interpolation_inputs(force_constants: aiida.orm.Data, qpoints: aiida.orm.KpointsData, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run interpolate_phonon_modes() as a PythonJob.

qpoints is a native KpointsData q-point specification, deserialized to a fractional-coordinate array before interpolation. The returned modes are serialized to a QpointPhononModesData.

Parameters

force_constants

Force constants node.

qpoints

q-point path or mesh.

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

aiida_alc_ins.pythonjobs.prepare_read_force_constants_inputs(castep_file: str | aiida.orm.SinglefileData, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run read_force_constants_from_castep() as a PythonJob.

The CASTEP file is staged into the job’s working directory via upload_files (mirroring how a real remote calculation stages its inputs); the function then reads it by basename and returns a ForceConstants serialized to a ForceConstantsData node.

Note

This builder demonstrates PythonJob file staging; none of this package’s workflows use it. Workflows that accept a castep_file read it in-process instead: the read takes a fraction of a second, so dispatching it as a job adds overhead without benefit.

Parameters

castep_file

CASTEP .castep_bin or .check file path or SinglefileData node.

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

aiida_alc_ins.pythonjobs.prepare_read_phonopy_inputs(summary: str | aiida.orm.SinglefileData, force_constants: str | aiida.orm.SinglefileData, born: str | aiida.orm.SinglefileData | None = None, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run read_force_constants_from_phonopy() as a PythonJob.

Note

Demonstrates PythonJob file staging; no workflow uses it. Workflows read Phonopy files in-process through force_constants.phonopy. Likely to be removed before version 1.0.

The summary (phonopy.yaml), force_constants and optional born files are staged into the working directory via upload_files; the function reads them by basename and returns a ForceConstantsData node.

Parameters

summary

Path or SinglefileData for Phonopy summary YAML file.

force_constants

Path or SinglefileData for Phonopy force constants file.

born

Optional path or SinglefileData for Born effective charges.

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

aiida_alc_ins.pythonjobs.prepare_dispersion_inputs(force_constants: aiida.orm.Data, q_spacing: float = 0.025, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build the input dict to run calculate_dispersion() as a PythonJob.

Parameters

force_constants

A ForceConstantsData node. It is deserialized to a Euphonic ForceConstants before the function runs.

q_spacing

Target q-point spacing in 1/Angstrom.

computer, code

Standard AiiDA execution targets. If code is None, aiida-pythonjob resolves/creates a Python code on computer.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

Returns

dict

Inputs to launch with aiida.engine.run/submit and aiida_pythonjob.PythonJob.

aiida_alc_ins.pythonjobs.prepare_dos_inputs(force_constants: aiida.orm.Data, q_spacing: float = 0.1, energy_spacing: float = 1.0, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run calculate_dos() as a PythonJob.

q_spacing is the target Monkhorst-Pack grid spacing (1/Angstrom) and energy_spacing the DOS bin width (meV). The returned euphonic Spectrum1D is serialized to a native XyData.

Parameters

force_constants

Force constants node.

q_spacing

Target Monkhorst-Pack grid spacing in 1/Angstrom.

energy_spacing

DOS energy bin width in meV.

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

aiida_alc_ins.pythonjobs.prepare_grid_interpolation_inputs(force_constants: aiida.orm.Data, q_spacing: float = 0.1, *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run interpolate_phonon_modes_on_grid() as a PythonJob.

q_spacing is the target Monkhorst-Pack grid spacing (1/Angstrom), matching prepare_dos_inputs()’s convention. Used by ToscaFromForceConstantsWorkChain to obtain a powder-average q-point sampling for the TOSCA intensity calculation, as distinct from prepare_interpolation_inputs()’s caller-supplied path (used for a band structure).

Parameters

force_constants

Force constants node.

q_spacing

Target Monkhorst-Pack grid spacing in 1/Angstrom.

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.

aiida_alc_ins.pythonjobs.prepare_tosca_spectrum_inputs(modes: aiida.orm.Data, temperature: float = 10.0, energy_spacing: float = 10.0, energy_max: float = 4000.0, detector_angles: list[float] | None = None, final_energy: float = 32.0, energy_unit: str = '1/cm', *, computer: str | aiida.orm.Computer = 'localhost', code: aiida.orm.AbstractCode | None = None, **kwargs: Any) → dict[str, Any][source]

Build inputs to run calculate_tosca_spectrum() as a PythonJob.

modes is a QpointPhononModesData node, deserialized to a Euphonic QpointPhononModes before the function runs. The returned Spectrum1DCollection – the full, ungrouped line set – is serialized to a single native XyData with one y array per line (see aiida_alc_ins.conversions.spectrum_collection_to_xydata()).

detector_angles defaults to None here (rather than a mutable literal default) and is passed through unchanged; calculate_tosca_spectrum() supplies the actual default (TOSCA’s two banks) so it is documented in one place.

Parameters

modes

Phonon modes node.

temperature

Sample temperature in kelvin.

energy_spacing

Energy bin width in energy_unit.

energy_max

Maximum energy in energy_unit.

detector_angles

Scattering angles in degrees.

final_energy

Final neutron energy in energy_unit.

energy_unit

Energy unit string (e.g. ‘1/cm’).

computer, code

Standard AiiDA execution targets.

kwargs

Extra arguments forwarded to prepare_pythonjob_inputs(), such as metadata={"options": {"resources": {"num_cpus": 1}}} for scheduler options or upload_files, parent_folder, and process_label.