Troubleshooting Guide

This guide covers common issues and their solutions when using Auto3D.

Installation Issues

“No module named ‘Auto3D’”

Problem: Python can’t find Auto3D after installation.

Solutions:

Verify installation:
```
pip show Auto3D
```
Check you’re in the correct environment:
```
which python
conda info --envs
```

Reinstall:

pip uninstall Auto3D
pip install Auto3D

“No module named ‘torch’”

Problem: PyTorch not installed or incompatible version.

Solutions:

Install PyTorch:

# CPU only
pip install torch

# With CUDA
pip install torch --index-url https://download.pytorch.org/whl/cu118

Check version compatibility (requires PyTorch >= 2.1.0):
```
import torch
print(torch.__version__)
```

“No module named ‘rdkit’”

Problem: RDKit not installed.

Solutions:

Install via conda (recommended):
```
conda install -c conda-forge rdkit
```
Or via pip:
```
pip install rdkit
```

GPU Issues

CUDA Out of Memory

Problem: GPU runs out of memory during optimization.

Solutions:

Reduce batch size:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    batchsize_atoms=512,  # Reduce from default 1024
)

Use single model instead of ensemble:

export AUTO3D_USE_ENSEMBLE=0
auto3d run input.smi --k=1 --gpu

Process smaller chunks:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    capacity=20,  # Fewer molecules per GB
)

Use CPU mode:
```
auto3d run input.smi --k=1 --no-gpu
```

“CUDA not available”

Problem: PyTorch doesn’t detect GPU.

Solutions:

Check CUDA installation:
```
nvidia-smi
nvcc --version
```

Verify PyTorch CUDA support:

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")

Reinstall PyTorch with CUDA:

pip uninstall torch
pip install torch --index-url https://download.pytorch.org/whl/cu118

“Invalid device ordinal”

Problem: Requested GPU index doesn’t exist.

Solutions:

List available GPUs:

import torch
print(f"GPU count: {torch.cuda.device_count()}")
for i in range(torch.cuda.device_count()):
    print(f"  GPU {i}: {torch.cuda.get_device_name(i)}")

Use valid index:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    gpu_idx=0,  # Use first GPU
)

Input/Output Issues

“Invalid SMILES”

Problem: Input file contains unparseable SMILES.

Solutions:

Validate input first:
```
auto3d validate input.smi
```

Check SMILES with RDKit:

from rdkit import Chem

with open("input.smi") as f:
    for i, line in enumerate(f):
        smiles = line.strip().split()[0]
        mol = Chem.MolFromSmiles(smiles)
        if mol is None:
            print(f"Line {i+1}: Invalid SMILES: {smiles}")

Remove problematic entries and rerun.

“Empty output file”

Problem: Output SDF is empty or missing.

Solutions:

Check log for errors:
```
cat auto3d.log | grep -i error
```
Ensure at least one molecule is valid

Check that k or window is set:

# Wrong: neither set
config = Auto3DOptions(path="input.smi")

# Correct: set k or window
config = Auto3DOptions(path="input.smi", k=1)

“File not found”

Problem: Input file path is incorrect.

Solutions:

Use absolute path:

import os
config = Auto3DOptions(
    path=os.path.abspath("input.smi"),
    k=1,
)

Check file exists:
```
ls -la input.smi
```

Optimization Issues

Optimization Not Converging

Problem: Structures don’t converge within max steps.

Solutions:

Increase max steps:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    opt_steps=5000,  # Increase from 2000
)

Relax convergence threshold:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    convergence_threshold=0.02,  # Looser than 0.01
)

Check for problematic structures (strained rings, unusual bonding)

NaN Energies

Problem: Optimization produces NaN values.

Solutions:

This usually indicates problematic geometry. Try:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    max_confs=50,  # More initial conformers
)

Check for unsupported elements:

from rdkit import Chem

mol = Chem.MolFromSmiles(smiles)
elements = set(atom.GetSymbol() for atom in mol.GetAtoms())
print(f"Elements: {elements}")

# AIMNET supports: H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I
# ANI supports: H, C, N, O, F, S, Cl

Use a different engine:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    optimizing_engine="ANI2x",  # Try different engine
)

Slow Performance

Problem: Processing is slower than expected.

Solutions:

Enable GPU:

config = Auto3DOptions(path="input.smi", k=1, use_gpu=True)

Use faster engine:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    optimizing_engine="ANI2xt",  # Fastest
)

Enable TF32 on Ampere GPUs:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    allow_tf32=True,
)

Reduce conformer generation:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    max_confs=100,  # Limit initial conformers
    patience=150,   # Drop oscillating faster
)

Tautomer Issues

No Tautomers Generated

Problem: Tautomer enumeration produces no results.

Solutions:

Check molecule has tautomerizable groups (N-H, O-H, C=O, etc.)

Enable tautomer enumeration:

config = Auto3DOptions(
    path="input.smi",
    k=1,
    enumerate_tautomer=True,
    tauto_engine="rdkit",
)

Use correct function:

from Auto3D.tautomer import get_stable_tautomers

output = get_stable_tautomers(config, tauto_k=5)

OpenEye License Error

Problem: OEChem requires a license.

Solutions:

Use RDKit instead:

config = Auto3DOptions(
    tauto_engine="rdkit",  # Free, no license
    isomer_engine="rdkit",
)

If you have a license, set environment:

export OE_LICENSE=/path/to/oe_license.txt

CLI Issues

Command Not Found

Problem: auto3d command not recognized.

Solutions:

Check installation:
```
pip show Auto3D
```

Ensure scripts directory is in PATH:

python -m Auto3D.cli.app run input.smi --k=1

Reinstall:
```
pip install --force-reinstall Auto3D
```

Check Python environment:

# Verify you're in the correct environment
which python
which auto3d

# If using conda
conda activate your_auto3d_env
auto3d --version

Invalid Option

Problem: CLI argument not recognized.

Solutions:

Check available options:

auto3d run --help
auto3d config --help
auto3d models --help

Use correct syntax:

# Correct
auto3d run input.smi --k=5

# Also correct
auto3d run input.smi --k 5

# Wrong (single dash for multi-char options)
auto3d run input.smi -k 5

Check spelling of options:

# Correct
auto3d run input.smi --engine=AIMNET

# Wrong
auto3d run input.smi --optimizing_engine=AIMNET

Configuration Issues

Problem: Configuration file not loading correctly.

Solutions:

Validate configuration file:
```
auto3d config validate my_config.yaml
```
Generate a fresh configuration template:
```
auto3d config init -o new_config.yaml
```
View current configuration:
```
auto3d config show my_config.yaml
```

Use presets for common scenarios:

auto3d config init -p quick -o quick.yaml
auto3d config init -p balanced -o balanced.yaml
auto3d config init -p thorough -o thorough.yaml

Input Validation

Problem: Input file has issues.

Solutions:

Validate before running:
```
auto3d validate input.smi
```

Check for common issues:

# Test with verbose output
auto3d run input.smi --k=1 -v

Test with a single molecule first:

echo "CCO ethanol" > test.smi
auto3d run test.smi --k=1

Shell Completion Not Working

Problem: Tab completion doesn’t work after installation.

Solutions:

Reinstall completion:

# For bash
auto3d --install-completion bash
source ~/.bashrc

# For zsh
auto3d --install-completion zsh
source ~/.zshrc

# For fish
auto3d --install-completion fish

Restart your terminal completely
Check shell type:
```
echo $SHELL
```

Getting Help

Collecting Debug Information

When reporting issues, include:

import sys
import torch
import Auto3D

print(f"Python: {sys.version}")
print(f"Auto3D: {Auto3D.__version__}")
print(f"PyTorch: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"CUDA version: {torch.version.cuda}")
    print(f"GPU: {torch.cuda.get_device_name(0)}")

Reporting Bugs

Check existing issues: https://github.com/isayevlab/Auto3D_pkg/issues
Include:
- Auto3D version
- Python/PyTorch versions
- Operating system
- Minimal reproducible example
- Full error traceback
Open new issue with template

Common Error Messages

Error	Solution
`ValueError: k and window cannot both be set`	Use only `k` OR `window`, not both
`RuntimeError: CUDA out of memory`	Reduce `batchsize_atoms` or use CPU
`ModuleNotFoundError: No module named 'torchani'`	Install TorchANI: `conda install -c conda-forge torchani`
`FileNotFoundError: input.smi`	Check file path exists
`KeyError: 'E_tot'`	Output file is corrupted; rerun
`torch.cuda.OutOfMemoryError`	Reduce batch size or use fewer GPUs