AtomWorks 2.x → 3.0: short migration guide

This guide covers the main I/O changes when moving from AtomWorks 2.x to 3.0: parser configuration, charges and bonds, alternate conformers, and CIF writing. See the detailed guide for examples and compatibility details.

1. Put parser options in ParseConfig

The result still contains asym_unit, assemblies, chain_info, ligand_info, metadata, and extra_info for ordinary inputs. Use source (or the first positional argument), and make processing choices explicit:

from atomworks.io import parse
from atomworks.io.config import ParseConfig

config = ParseConfig.from_preset(
    "rcsb",
    hydrogen_policy="remove",
    build_assembly="first",
)
result = parse("structure.cif", config=config)

Surviving bare keyword options and filename= remain accepted with deprecation warnings. Remove fix_formal_charges and fix_bond_types: these flags no longer exist; completing missing atoms now includes chemistry sanitization. hydrogen_policy="infer" is no longer a supported parser policy; use explicit protonation if needed. Parser and configuration.

2. Check changed charges and covalent chemistry

Covalent linkage processing corrects leaving atoms, bond orders, hydrogen counts and formal charges, including incorrectly charged amide nitrogens. Link validation also checks whether connections fit the selected conformer and supported chemistry; ambiguous or unsupported products can now raise an error and require explicit chemical definitions. A model trained on 2.x features can be sensitive to these changed inputs. Keep its old preprocessing environment available, compare features on representative covalent complexes, and evaluate the checkpoint before switching production inference. There is no parser switch that reproduces all historical chemistry. See the detailed chemistry guidance for affected cases and how to handle them.

3. Choose alternate conformers deliberately

CIF parsing supports altloc="first" (default), a specific letter, "random_per_chain", or "random_clash_aware". Set altloc_seed for reproducible random selection. This selects a conformer; it does not return an exhaustive ensemble. PDB parsing only supports "first". Keep "first" for an initial migration comparison; adopt random selection as a separate data change. Record the seed with the parsed data. Options.

4. Use CIF to preserve structure chemistry and annotations

The writer and parser now support substantially richer AtomArray → CIF → AtomArray round trips, including custom component chemistry. Use to_cif_file(), retain component/entity categories, and reload with add_missing_atoms=False when preserving an already prepared structure. For registered StandardAnnotations, also set return_atom_array_plus=True, load_standard_annotations=True on reload. Assemblies with repeated chain identities need an explicit chain_disambiguation policy.

Round trips are structural, not byte-for-byte identity: coordinates are rounded to three decimals, order/dtypes and some derived IDs may change, and arbitrary annotations require explicit handling. See the worked example and limits.

5. Refresh the environment and parser caches

Install into a fresh environment and regenerate your dependency lock: AtomWorks 3.0 requires exactly biotite==1.6.0 (2.2.1 used 1.4.0), pyarrow>=23.0.1, and Python ≥3.11. Rebuild or separate parser caches when adopting the new chemistry and conformer policies. Dependencies.

Before switching, compare a small fixed set of structures under both environments: selected model/assembly, atom identities and counts, bonds, charges and implicit hydrogens. If these structures feed an existing model, check its predictions with the new parser output.