RMG Analyzer

nexus.rmg_analyzer.as_float(text)

Convert a finite RMG-formatted number to a float when possible.

nexus.rmg_analyzer.normalize_line(line)

Collapse whitespace in an output line.

nexus.rmg_analyzer.line_numbers(line)

Return all finite, whitespace-delimited RMG numbers in a line.

class nexus.rmg_analyzer.RmgOutData(filepath, input=None)

Bases: DevBaseNexus

Read an RMG output file and collect results appropriate to its run mode.

Parameters:

filepathstr or os.PathLike

Path to the RMG log output file.

Attributes:

pathstr

Directory containing the output file.

abspathstr

Absolute path to the output directory.

outfile_namestr

Name of the RMG output file.

inputRmgInput or None

Parsed control input when the referenced input file is available.

setup_infoobj

Parsed setup sections and derived setup data. Derived members include run_mode, the initial structure, cell volume information, and crystal and Cartesian k_points with optional weights.

run_modestr, tuple, or None

Short RMG calculation mode: "scf", "nscf", "band", "exx", "relax", "md_VE", "md_TE", "tddft", "stm", or "neb". Input/output disagreement is represented by (input_mode, output_mode).

input_run_mode, output_run_modestr or None

Calculation modes independently identified from the referenced input and the output log.

reader_modestr or None

Mode used to select the structured reader stack. Output-log data take precedence over referenced-input data for this purpose.

run_mode_detectedbool

Whether a mode was available to select the structured reader stack.

convergenceobj or None

Electronic and ionic convergence indicators and event counts.

timingobj or None

Total, per-step, and section-resolved timing data in seconds.

energiesobj or None

Energy data with history, units, final, final_units, direct, and direct_units members.

electronicobj or None

Fermi energies, band edges, gaps, k-points, eigenvalues, and occupations, charge, magnetization, force, volume, and per-atom energy data when reported.

scfobj or None

SCF energy components, iteration indices, residuals, and timing data.

ionsobj or None

Detailed ionic steps; cell, position, force, charge, magnetization, and maximum-force histories; associated units; and a structure_history constructed with the cell reported for each step.

stressobj or None

Stress-tensor and hydrostatic-pressure histories, their units, and the final pressure.

bandsobj or None

Spin-indexed band-path distances and band energies read from companion band-structure files.

mdobj or None

Molecular-dynamics step, energy, temperature, and displacement arrays.

md_statsobj or None

Statistical summaries for the molecular-dynamics arrays.

tddftobj or None

Time-dependent energy changes and spin-resolved dipole histories read from companion files.

nebobj or None

NEB controller and parallel settings, input and final path structures, reaction coordinate, image energies and barriers, and local-image histories. final_images contains ordered final structures, positions, cells, atoms, units, and source files when available.

produced_filesobj or None

Paths to recognized QMCPACK restart, EXX integral, or STM files.

Methods

copy()
read_band()	Read spin-resolved band structures from companion data files.
read_cell_events(lines[, initial_structure])	Return line-indexed lattice cells reported in an RMG output.
read_convergence(lines)	Read electronic and ionic convergence messages.
read_electronic(lines)	Parse electronic quantities exposed by RmgAnalyzer.
read_energies(lines)	Read eigenvalue-sum and direct total-energy histories.
read_ion_records(lines[, initial_structure])	Return ionic records and structures without binding analyzer data.
read_ions(lines)	Read ionic records, cells, and trajectory-level structures.
read_md(lines)	Read molecular-dynamics records and compute summary statistics.
read_neb(lines)	Read NEB controller, path, energy, and final-image data.
read_produced_files()	Locate recognized files produced by EXX, STM, and SCF runs.
read_scf(lines)	Read SCF energy components, iteration indices, residuals, and times.
read_setup_info(lines)	Read setup sections, the run mode, and the initial structure.
read_stress(lines)	Parse stress tensors and derive hydrostatic pressures.
read_tddft()	Read TDDFT energy and spin-resolved dipole time series.
read_timing(lines)	Read total, per-step, and section-resolved timing information.
save([filepath])

clear
error
items
keys
load
nxs_print
update
values
warn

Raises:

TypeError

If filepath is not a string or path-like object.

FileNotFoundError

If filepath does not exist.

IsADirectoryError

If filepath does not identify a regular file.

Notes

All result members are initialized to None. convergence and timing apply to all supported modes. energies, scf, ions, and stress apply to SCF, NSCF, relaxation, molecular dynamics, TDDFT, and NEB modes. electronic also applies to band mode. bands, md and md_stats, tddft, and neb are specific to their corresponding modes. produced_files applies to SCF, EXX, and STM. A member remains None when its data cannot be obtained. History arrays are ordered as they occur in the output. When no run mode can be detected, all readers are attempted permissively. When a mode is detected, only the corresponding structured reader stack is attempted. Readers skip absent or malformed records they recognize, but unexpected reader exceptions are not suppressed.

Independently identified input and output modes are normally stored as a single string. A disagreement is retained as (input_mode, output_mode) rather than terminating parsing. The expected SCF input associated with an NEB image calculation is represented as "neb".

number_pattern = '[-+]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[EeDd][-+]?\\d+)?'

read_setup_info(lines)

Read setup sections, the run mode, and the initial structure.

Binds setup_info to an obj containing normalized setup blocks and derived grid, lattice, ion, k-point, and structure data. When the referenced control file is available, also binds input.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_convergence(lines)

Read electronic and ionic convergence messages.

Binds convergence to an obj containing nullable status values and electronic success and failure counts.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_timing(lines)

Read total, per-step, and section-resolved timing information.

Binds timing to an obj measured in seconds, with individual timing rows stored under timing.sections.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_energies(lines)

Read eigenvalue-sum and direct total-energy histories.

Binds energies to an obj containing the history arrays and their units, as well as the final eigenvalue-sum energy and its units.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_scf(lines)

Read SCF energy components, iteration indices, residuals, and times.

Binds scf to an obj containing NumPy histories. Energies are in Hartree and times are in seconds.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_ions(lines)

Read ionic records, cells, and trajectory-level structures.

read_stress(lines)

Parse stress tensors and derive hydrostatic pressures.

Binds stress to an obj containing tensor and pressure histories, their shared unit label, and the final hydrostatic pressure.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_electronic(lines)

Parse electronic quantities exposed by RmgAnalyzer.

Binds electronic to an obj containing Fermi energies, band edges, gaps, charge and magnetization values, summed forces, per-atom volume and energy, k-point-major eigenvalues and occupations, and k-points.

Parameters:

lineslist of str

Complete RMG log split into lines.

read_md(lines)

Read molecular-dynamics records and compute summary statistics.

read_band()

Read spin-resolved band structures from companion data files.

read_tddft()

Read TDDFT energy and spin-resolved dipole time series.

read_neb(lines)

Read NEB controller, path, energy, and final-image data.

Final reported image geometries are collected in final_images in path order. Its position and cell arrays are in bohr and remain None unless every image supplies compatible data.

read_produced_files()

Locate recognized files produced by EXX, STM, and SCF runs.

Binds produced_files to an obj containing the QMCPACK restart path when the file exists.

read_cell_events(lines, initial_structure=None)

Return line-indexed lattice cells reported in an RMG output.

read_ion_records(lines, initial_structure=None)

Return ionic records and structures without binding analyzer data.

class nexus.rmg_analyzer.RmgAnalyzer(input=None, outfile=None, *, analyze=False, path=None, strict=True, required=None)

Bases: SimulationAnalyzer

Analyze an RMG simulation or log output file.

Parameters:

inputSimulation, RmgInput, str, os.PathLike, or None, optional

RMG simulation, parsed input, input-file path, or directory in which an input can be discovered.

outfilestr, os.PathLike, or None, optional

Path to RMG log output. Relative paths are resolved below path.

analyzebool, default=False

If True, parse the RMG output during initialization.

pathstr, os.PathLike, or None, optional

Base directory for relative paths and log-output discovery.

strictbool, default=True

Require the configured log output to be a regular file when analysis begins. Top-level run types discovered from the referenced input and output log must also agree. If False, a missing or non-file path completes analysis with empty results and run-type disagreement is retained as a tuple.

requiredstr, iterable of str, or None, optional

Query quantities whose absence should raise RuntimeError instead of returning None.

Attributes:

pathstr or None

Directory containing the RMG log output file.

abspathstr or None

Absolute path to the output directory.

outfile_namestr or None

Name of the RMG log output file.

infoobj

General analyzer metadata.

inputRmgInput or None

RMG input reconstructed from the referenced control file when it is available.

run_modestr, tuple, or None

Short RMG calculation mode determined during analysis: "scf", "nscf", "band", "exx", "relax", "md_VE", "md_TE", "tddft", "stm", or "neb". Disagreement between a referenced input and output log is represented by (input_mode, output_mode).

resultsRmgOutData, obj, or None

Parsed setup and mode-specific RMG output data, an empty result object after permissive missing-file analysis, or None before analysis.

requiredset of str

Validated query quantities subject to required-data behavior.

analysis_state{‘not_analyzed’, ‘analyzing’, ‘analyzed’}

Current analysis lifecycle state.

source_statusobj

Diagnostic referenced-input and output-log states.

Methods

initial_structure(units=’A’)	(Structure or None) Input atomic structure in Angstrom ('A') or bohr ('B').
energy(units=’Ha’)	(float or None) Final eigenvalue-sum energy in 'eV', 'Ha', or 'Ry'. Available for electronic, ionic, molecular-dynamics, TDDFT, and NEB calculations, but not band, EXX, or STM calculations.
kpoints(units=’B’)	(numpy.ndarray or None) Cartesian k-points in inverse Angstrom or inverse bohr with shape (nkpoints, 3). The unit argument is 'A' or 'B'. Electronic output data are preferred over setup data when both are available.
kweights()	(numpy.ndarray or None) Dimensionless k-point weights with shape (nkpoints,).
eigenvalues(units=’eV’)	(numpy.ndarray or None) Kohn–Sham eigenvalues in 'eV', 'Ha', or 'Ry'. The leading dimension has length nkpoints; remaining dimensions represent spin, when present, and bands. Band calculations are read from their spin-resolved companion files.
occupations()	(numpy.ndarray or None) Dimensionless Kohn–Sham occupations. The leading dimension has length nkpoints; remaining dimensions represent spin, when present, and bands.
Ef(units=’eV’)	(float or None) Final Fermi energy in 'eV', 'Ha', or 'Ry'.
Evbm(units=’eV’)	(float or None) Final reported valence-band maximum in selected energy units.
Ecbm(units=’eV’)	(float or None) Final reported conduction-band minimum in selected energy units.
band_gap(units=’eV’)	(float or None) Final reported electronic band gap in selected energy units.
fractional_occs(tol=1e-3)	(bool or None) Whether any occupation is farther than tol from both empty and full occupation.
relaxed_structure(units=’A’)	(Structure or None) Final structure from the ionic history of a relaxation or local NEB image, in Angstrom ('A') or bohr ('B').
forces(units=’eV/A’)	(numpy.ndarray or None) Final ionic forces with shape (natoms, 3). Available units are 'eV/A', 'Ry/B', and 'Ha/B'.
stress(units=’GPa’)	(numpy.ndarray or None) Final stress tensor with shape (3, 3). Available units are 'Pa', 'bar', 'kbar', 'Mbar', 'GPa', 'atm', 'eV/A^3', 'Ha/Bohr^3', and 'Ry/Bohr^3'.
pressure(units=’GPa’)	(float or None) Final hydrostatic pressure in the units accepted by stress.
require(*quantities)	Add query quantities to the required-data policy without parsing.
available(*quantities)	(bool) Report whether every named quantity is currently queryable.

Raises:

TypeError

If an input or path argument has an unsupported type.

FileNotFoundError

During strict analysis, if the configured output path does not exist.

IsADirectoryError

During strict analysis, if the configured output path is not a file.

ValueError

If a query receives unsupported units or a quantity name is invalid.

Notes

Initial structures and setup k-points are queryable for every supported mode. Eigenvalues additionally support band mode. Energy, occupations, band-edge quantities, forces, stress, and pressure apply to SCF, NSCF, relaxation, molecular-dynamics, TDDFT, and NEB modes. Relaxed structures apply to relaxation and NEB modes. Parsed data are returned even when unusual for the identified mode. Otherwise, a query returns None when applicable data were not parsed unless the quantity is required. Calling a query before analysis or for a definitively unsupported mode raises RuntimeError. Supplying unsupported units raises ValueError.

all_modes = frozenset({'band', 'exx', 'md_TE', 'md_VE', 'neb', 'nscf', 'relax', 'scf', 'stm', 'tddft'})

electronic_modes = frozenset({'md_TE', 'md_VE', 'neb', 'nscf', 'relax', 'scf', 'tddft'})

eigenvalue_modes = frozenset({'band', 'md_TE', 'md_VE', 'neb', 'nscf', 'relax', 'scf', 'tddft'})

relaxation_modes = frozenset({'neb', 'relax'})

quantity_names = frozenset({'Ecbm', 'Ef', 'Evbm', 'band_gap', 'eigenvalues', 'energy', 'forces', 'fractional_occs', 'initial_structure', 'kpoints', 'kweights', 'occupations', 'pressure', 'relaxed_structure', 'stress'})

pressure_units = mappingproxy({'Pa': 100000000.0, 'bar': 1000.0, 'kbar': 1.0, 'Mbar': 0.001, 'GPa': 0.1, 'atm': 986.9232667160128, 'eV/A^3': 0.0006241509752302815, 'Ha/Bohr^3': 3.398931451903016e-06, 'Ry/Bohr^3': 6.797862903806032e-06})

require(*quantities)

Add query quantities to the required-data policy.

Parameters:

*quantitiesstr

Case-sensitive names from quantity_names.

Returns:

None

Notes

This method only updates required. It does not parse files, reanalyze existing results, or check current availability.

available(*quantities)

Return whether all named query quantities are available.

Parameters:

*quantitiesstr

Case-sensitive names from quantity_names.

Returns:

bool

True only when every named query returns a value other than None. With no names, returns True.

Raises:

RuntimeError

If analysis has not completed.

ValueError

If any quantity name is invalid.

Notes

Required-data and run-mode-applicability errors are suppressed for this check. The method never parses or reanalyzes data.

initial_structure(units='A')

Return the initial structure.

Parameters:

units{‘A’, ‘B’}, default=’A’

Requested length unit: Angstrom or bohr.

Returns:

Structure or None

Structure with axes (3, 3) and positions (natoms, 3), or None.

energy(units='Ha')

Return the final total energy.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’Ha’

Requested energy unit.

Returns:

float or None

Final total energy, or None.

kpoints(units='B')

Return Cartesian k-points.

Parameters:

units{‘A’, ‘B’}, default=’B’

Reciprocal length unit, inverse Angstrom or inverse bohr.

Returns:

numpy.ndarray or None

Float array of shape (nkpoints, 3), or None.

kweights()

Return k-point integration weights.

Returns:

numpy.ndarray or None

One-dimensional float array with shape (nkpoints,), or None.

eigenvalues(units='eV')

Return Kohn–Sham eigenvalues.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’eV’

Requested energy unit.

Returns:

numpy.ndarray or None

Float array shaped (nkpoints, nbands) or (nkpoints, 2, nbands) for collinear spin, or None.

occupations()

Return Kohn–Sham occupations.

Returns:

numpy.ndarray or None

Dimensionless float array with the shape returned by eigenvalues, or None.

Ef(units='eV')

Return the final Fermi energy.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’eV’

Requested energy unit.

Returns:

float or None

Fermi energy, or None.

Evbm(units='eV')

Return the valence-band maximum.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’eV’

Requested energy unit.

Returns:

float or None

Valence-band maximum, or None.

Ecbm(units='eV')

Return the conduction-band minimum.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’eV’

Requested energy unit.

Returns:

float or None

Conduction-band minimum, or None.

band_gap(units='eV')

Return the final band gap.

Parameters:

units{‘eV’, ‘Ha’, ‘Ry’}, default=’eV’

Requested energy unit.

Returns:

float or None

Fundamental band gap, or None.

fractional_occs(tol=0.001)

Determine whether any occupation is fractional.

Parameters:

tolfloat, default=1e-3

Absolute tolerance for identifying empty and full occupations.

Returns:

bool or None

True for a fractional occupation, or None if unavailable.

relaxed_structure(units='A')

Return the final ionic structure.

Parameters:

units{‘A’, ‘B’}, default=’A’

Requested length unit: Angstrom or bohr.

Returns:

Structure or None

Final structure with axes (3, 3) and positions (natoms, 3), or None.

forces(units='eV/A')

Return final ionic forces.

Parameters:

units{‘eV/A’, ‘Ry/B’, ‘Ha/B’}, default=’eV/A’

Requested energy-per-length unit.

Returns:

numpy.ndarray or None

Float array of shape (natoms, 3), or None.

stress(units='GPa')

Return the final stress tensor.

Parameters:

units{‘Pa’, ‘bar’, ‘kbar’, ‘Mbar’, ‘GPa’, ‘atm’, ‘eV/A^3’, ‘Ha/Bohr^3’, ‘Ry/Bohr^3’}, default=’GPa’

Requested pressure or energy-density unit.

Returns:

numpy.ndarray or None

Float array of shape (3, 3), or None.

pressure(units='GPa')

Return final hydrostatic pressure.

Parameters:

units{‘Pa’, ‘bar’, ‘kbar’, ‘Mbar’, ‘GPa’, ‘atm’, ‘eV/A^3’, ‘Ha/Bohr^3’, ‘Ry/Bohr^3’}, default=’GPa’

Requested pressure or energy-density unit.

Returns:

float or None

Final hydrostatic pressure, or None.

analyze()

Parse the configured RMG output into an RmgOutData instance.