Migrating from v2 to v3

Auto3D v3.0 introduces significant improvements including a modern CLI, type-safe configuration, and cleaner architecture. This guide helps you update your code and workflows.

Breaking Changes

Python Version

Auto3D v3.0 requires Python 3.10 or later. If you’re using an older Python version, you’ll need to upgrade your environment.

API Changes

The options() function has been removed

The most significant change is the removal of the options() function. Replace it with the Auto3DOptions dataclass:

Before (v2.x):

from Auto3D.auto3D import options, main

args = options("input.smi", k=1, use_gpu=False)
out = main(args)

After (v3.0):

from Auto3D import Auto3DOptions, main

config = Auto3DOptions(path="input.smi", k=1, use_gpu=False)
out = main(config)

Import paths simplified

The main imports are now available directly from the Auto3D package:

Before (v2.x):

from Auto3D.auto3D import options, main, smiles2mols
from Auto3D.SPE import calc_spe
from Auto3D.ASE.thermo import calc_thermo
from Auto3D.ASE.geometry import opt_geometry

After (v3.0):

from Auto3D import Auto3DOptions, main, smiles2mols
from Auto3D import calc_spe, calc_thermo, opt_geometry

CLI Changes

New subcommand structure

The CLI now uses subcommands for better organization:

Before (v2.x):

auto3d parameters.yaml
auto3d input.smi --k=1

After (v3.0):

# Primary way to run
auto3d run input.smi --k=1

# With config file
auto3d run input.smi -c config.yaml

# New commands
auto3d config init          # Generate config template
auto3d models list          # List available models
auto3d validate input.smi   # Validate input file

# Legacy syntax still works for backwards compatibility
auto3d parameters.yaml

Default Value Changes

Some default values have been adjusted for better performance:

Parameter

v2.x Default

v3.0 Default

Reason

opt_steps

5000

2000

Most structures converge much earlier

patience

1000

250

Faster detection of oscillating structures

convergence_threshold

0.003 eV/Å

0.01 eV/Å

Sufficient for conformer ranking

If you need the old behavior, explicitly set these parameters:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    opt_steps=5000,
    patience=1000,
    convergence_threshold=0.003
)

New Features in v3.0

Modern CLI with Rich output

The new CLI provides:

  • Beautiful terminal output with progress bars

  • Helpful error messages with suggestions

  • Shell completion for bash, zsh, and fish

  • Configuration presets

# Enable shell completion
auto3d --install-completion bash

# View available models with details
auto3d models info AIMNET

Type-safe configuration

Auto3DOptions is a dataclass that validates parameters at creation time, catching errors early:

# This will raise an error immediately
config = Auto3DOptions(path="input.smi", k=1, window=5.0)  # Can't set both k and window

Model Factory API

New API for creating models directly:

from Auto3D import create_model

# Create a model for custom workflows
model = create_model("AIMNET", device="cuda:0")

# Use ensemble for higher accuracy (slower)
model = create_model("AIMNET", device="cuda:0", use_ensemble=True)

Environment variables

New environment variables for runtime configuration:

  • AUTO3D_COMPILE_MODEL=1 - Enable torch.compile for ANI models (~1.25x speedup)

  • AUTO3D_USE_ENSEMBLE=1 - Use ensemble model for AIMNet (higher accuracy)

Migration Checklist

  1. ☐ Update Python to 3.10+

  2. ☐ Replace from Auto3D.auto3D import options with from Auto3D import Auto3DOptions

  3. ☐ Replace options(path, ...) calls with Auto3DOptions(path=path, ...)

  4. ☐ Update CLI scripts to use auto3d run syntax

  5. ☐ Review default value changes and adjust if needed

  6. ☐ Test your workflows with the new version

Getting Help

If you encounter issues during migration: