SEAMM Read Structure Plug-in

A SEAMM plug-in to read common formats in computational chemistry

The current version uses Open Babel as an engine to parse various formats such as PDB, Mol2 or XYZ and transform them into the SEAMM structure format for further use in SEAMM flowcharts.

• Free software: BSD license

• Documentation: https://molssi-seamm.github.io/read_structure_step/index.html

• Code: https://github.com/molssi-seamm/read_structure_step

import read_structure_step
seamm_structure = read_structure_step.read("spc.xyz")

History

2026.9.15.1 – Bugfix: writing any extended XYZ file failed

• The helper added in 2026.9.15 was placed between the @register_writer decorator and the function it decorates, so the decorator bound the helper instead. Every attempt to write an extxyz file then failed with “TypeError: _latest_property() got an unexpected keyword argument ‘extension’”. The tests did not catch it because they call the helper directly and never go through the writer registry; there are now checks that the registered writer is the writer, and that a file can actually be written end to end.

2026.9.15 – Bugfix: wrong property written as REF_energy in extended XYZ

• A quantity averaged over an MD trajectory is stored alongside its statistics, named with a comma: ‘potential energy#LAMMPS#oplsaa+’ comes with ‘potential energy, stderr#…’, ‘, tau#…’ and ‘, inefficiency#…’. When searching for the energy, the pattern matched those too and the last match was taken, which selected ‘inefficiency’. That has no units, so writing an extxyz file at the end of an MD run failed with “Expression to parse as PlainQuantity cannot be an empty string”.

• The crash was the fortunate case. Had the ordering put ‘stderr’ last it would have been converted and written as REF_energy without complaint, putting the standard error of the energy into a reference-data file in place of the energy. The statistics are now excluded when choosing any property, for the energy, the stress, the gradients and the velocities alike.

• A property carrying no units is no longer written at all, with a warning saying why, rather than guessing at its scale.

2026.7.13 – Read and write per-atom charges in extended XYZ

• Extended-XYZ (.extxyz) files now round-trip per-atom charges. On writing, charges carried by the structure (the standard charge attribute, e.g. set by the Atomic Charges step) are emitted as a charge:R:1 column, to export charges for machine-learning training; no column is written when the structure has no charges. On reading, a charge:R:1 column is loaded back onto the structure’s charge attribute (when ‘save properties’ is on).

2026.1.6 – Bugfix: Fixed error reading multiple structure from .extxyz file

• Fixes a crash on reading multiple structures from a .extxyz file when using the system name from the file (“keep current name” or “title”) with a given configuration name, like “initial”.

2026.1.1 – Bugfix: Incorrect blockname used when reading CIF files

• The blockname, which can be used as the name of the system and/or configuration was incorrect when only some structures where read from a mult-block CIF file.

2025.11.26 – Added an option for whether to save properties and forces when reading

• The new option “Save properties” determines whether to save any properties, gradients, or velocities in the file to the configuration. If False, only the structure is loaded into the configuration.

2025.11.19 – Finalized support for ASE style .extxyz files

• Added handling of the system and configuration names encoded in the header of the files, both on writing and reading.

• Fixed errors in units for velocities

• Cleaned up and standardized handling of compressed (gzip and bzip2) files across the formats that support compression, currently CIF, SDF, and extended XYZ.

2025.11.11 – Added support for ASE style .extxyz files.

This release adds support for ASE (Atomic Simulation Environment) style extended XYZ files (.extxyz) with appropriate unit handling (eV, Å, and time = Å*amu^0.5/eV^0.5). The changes also introduce file appending capabilities and support for reading compressed (bz2) SDF files.

• Added complete .extxyz format reader and writer with ASE compatibility

• Added append mode option for file writers where applicable

• Added extra_attributes parameter for .extxyz files to include custom metadata

• Updated multiple file format handlers to support the new append functionality

2025.8.6 – Bugfix: Corrected handling of paths relative to the home directory

• The code did not correctly handle reading structures from files relative to home directories.

2025.5.14 – Standardized citations to OpenBabel

• Internal change which should not affect users.

2025.3.4 – Improved handling of system names in SDF files

• Switched to new handling of system and configuration names as properties in SDF files, rather than encoded in the title. This avoids problems with special characters in name, for example when using SMILES as the name.

2025.1.15 – Added ability to write using an arbitrary list of structures.

2025.1.3.1 – Bugfix: Issue with reading XYZ files

• If the XYZ file had the charge and spin multiplicity encoded in the comment line, and the spin multiplicity came before the charge, the spin multiplicity was not correctly set. This fixes that issue.

2025.1.3 – Enhancements to SDF and XYZ files

• Added more keywords to the header of XYZ files to allow for more flexibility in reading them. Specifically ‘title’, ‘model’, and ‘name’, which can be used to name the system and/or configuration.

• When reading SDF files, ‘keep current name’ will use the encoded system name in SDF files written by SEAMM, if it exists.

• Fixed minor issue writing SDF files where the ‘configurations’ widget was displayed when writing the current configuration. The widget is now correctly hidden.

2024.12.29 – Bugfix: Issue with reusing systems matching SDF files.

• The logic was faulty, so if the first structure in an SDF file was a configuration of an existing system, it was not added to the system correctly.

2024.12.7 – Minor update due to changes in molsystem

• The molsystem was updated to improve the handling of properties. This required changes in this module to match the new molsystem.

2024.11.29 – Added chemical formula as option for system/configuration names

2024.11.13 – Bugfix: Issues with the names of properties

• Fixed syntax of the properties pulled out from MOPAC encoded parameterization inputs.

2024.11.3 – Bugfix: MOPAC files with references in comments

• Fixed a bug that caused a crash when reading MOPAC files with references in the comments.

• Updated the MOPAC reader to the new approach for running MOPAC in the cases that it is needed: Z-matrices and mixed inputs that OpenBabel can’t handle.

2024.8.23 – Enhancements to directory handling

• Changed the handling of paths to make them relative to the directory that the step is running in. In a loop, for instance, files are relative to the iteration directory.

• When reading files, allow the syntax ‘job://<job number>/…’ to read files from another job. If the job number is omitted, so the prefix is ‘job:///…’, the top directory of the current job is used.

2024.7.28 – Added new names for systems and configurations

• Made the naming of systems and configurations consistent with the standard parameters for them in the GUI.

• Removed all “from file” options, replacing them with “title”, which means the title from the file, if it exists, or the filename if it doesn’t.

2023.11.16 – Bugfix: titles in SDF files

• Crashed reading some SDF files write by SEAMM due to the system and configuration names encoded in the title having multiple slashes (/).

2023.11.5 – Added writers for CIF and mmCIF.

2023.11.2 – Initial changes to structure handling

• Moving towards the standard structure handling that has developed across SEAMM.

2023.8.30 – Support for spacegroup symmetry

2023.7.28 – Implemented ranges for reading XYZ and SDF files.

2023.7.27.1 – Removed debug printing.

2023.7.27 – Support for .gz and .bz2 files, and multi-structure .xyz files

• Handle .gz and .bz2 files for .sdf and .xyz extensions.

• Handle multi-structure XYZ files with a blank line between records.

2023.7.6 – Bugfixes

• Fixed output of number of structures written to SDF files, which was off by 1.

• Cleaned up the output for the write-structure step

2023.1.30 – Fixed issue#43, duplicate systems or configuration created

• Reading a single structure from e.g. a .sdf file created a second system or configuration, depending on the stucture control options.

2023.1.24 – Added handler for XYZ files and added properties

• Added a custom handler for XYZ files to cope with some of the variant formats.

  • Supports files with no atom count on the first line

  • Supports the variant used in the Minnesota Solubility database, which has 3 header lines.

• Add capability to store properties into the database for formats such as MOPAC and SDF that can handle properties. Also can output the properties when writing the files.

• Fixed bugs if the system name or configuration name is not a string, but rather a number.

2022.10.28 – Fixed bug reading cif and mmcif files

• There was a bug that caused a crash when reading cif and mmcif files, and potentially some other formats. It has been fixed throughout.

• The standard error for properties were missing a commma in the property name. The comma is standard elsewhere in SEAMM so add it here: ‘<prop>, stderr’

2022.10.26 – Handling OpenBabel error messages for MOPAC .mop files

Hiding messages about errors Kekulizing structures, which doesn’t seem to be a serious issue, and printing any other messages as warnings.

2021.2.12 (12 February 2021)

• Updated the README file to give a better description.

• Updated the short description in setup.py to work with the new installer.

• Added keywords for better searchability.

2021.2.4 (4 February 2021)

Updated for compatibility with the new system classes in MolSystem 2021.2.2 release.

2020.12.5 (5 December 2020)

Internal: switching CI from TravisCI to GitHub Actions, and in the process moving documentation from ReadTheDocs to GitHub Pages where it is consolidated with the main SEAMM documentation.

2020.8.1 (1 August 2020)

Removed leftover debug print statements.

0.9 (15 April 2020)

• General bug fixing and code cleanup.

• Part of release of all modules.

0.7.1 (23 November 2019)

First release on PyPI.