atomate: Materials Science Workflows with FireWorks

1.1.0 · active · verified Fri Apr 17

atomate provides pre-built, robust workflows for computational materials science, primarily leveraging the VASP code and integrating with the FireWorks workflow management system. It builds upon pymatgen, custodian, and maggma for comprehensive materials data handling and job execution. The current version is 1.1.0, with releases occurring a few times a year to add features and fix bugs.

Common errors

```
ModuleNotFoundError: No module named 'fireworks'
```
cause The FireWorks library, a core dependency for atomate's workflow engine, is not installed.

fix Install FireWorks: `pip install fireworks`
```
fireworks.utilities.fw_config.ConfigError: Cannot find FireWorks configuration file!
```
cause atomate workflows, through FireWorks, require a configuration file (`FW_CONFIG_FILE`) to connect to a MongoDB database for job management.

fix Set up your FireWorks configuration file. Create a `FW_CONFIG_FILE.yaml` (or similar) and set the environment variable: `export FW_CONFIG_FILE=/path/to/your/FW_CONFIG_FILE.yaml`. Consult FireWorks documentation for details.
```
KeyError: 'db_file'
```
cause Some atomate workflows or firetasks expect a 'db_file' parameter or a configured default for database interaction, which may be missing or incorrectly set.

fix Explicitly pass `db_file='path/to/db.json'` or `db_file=None` if using FireWorks' default config. Ensure your FireWorks configuration (via `FW_CONFIG_FILE`) correctly points to your database.
```
ValueError: vasp_cmd is None or not found. Please provide vasp_cmd in the config or as an argument.
```
cause The command to execute VASP was not provided to the workflow or firetask, and no default was found in the configuration.

fix Pass `vasp_cmd='vasp_std'` (or your specific VASP executable path) directly to the workflow/firetask, or set it as an environment variable (e.g., `export VASP_CMD=/usr/local/bin/vasp_std`).

Warnings

breaking Major architectural changes occurred in atomate prior to version 1.0 (e.g., introduction of 'atomate2' as a separate project with jobflow). If migrating from very old versions (<0.9.x), expect significant API differences.
Fix: Consult the atomate 1.x documentation and relevant FireWorks documentation for updated API calls. Consider a fresh installation if upgrading from highly outdated versions.
gotcha atomate relies heavily on FireWorks for workflow management. You must have a working FireWorks installation with a configured `FW_CONFIG_FILE` pointing to a MongoDB instance to run workflows.
Fix: Follow the FireWorks installation guide (fireworks.readthedocs.io) to set up your `FW_CONFIG_FILE` and ensure MongoDB is running and accessible. Common environment variables are `FW_CONFIG_FILE` and `VASP_CMD`.
gotcha VASP executable must be available on your system where FireWorks jobs are launched. The `vasp_cmd` parameter in workflows and firetasks specifies how to call VASP.
Fix: Ensure VASP is installed, compiled, and its executable is in your system's PATH or explicitly provided to `vasp_cmd` (e.g., `vasp_cmd='/path/to/vasp_std'`).
gotcha The `pip install atomate` command installs a minimal set of dependencies. For full functionality or specific integrations, you may need to install additional packages (e.g., `pymatgen[full]`, `atomate-vasp` if using split versions, or other specific database connectors).
Fix: Review the `atomate` documentation or `setup.py` on GitHub for required optional dependencies based on your specific use case. Consider `pip install "pymatgen[full]"` as a common addition.

Install

pip install atomate Basic Installation

Imports

wf_static
```
from atomate.vasp.workflows.base import wf_static
```
Common workflow for static energy calculation in VASP.
RunVaspCustodian
```
from atomate.vasp.firetasks.run_calc import RunVaspCustodian
```
A Firetask for running VASP calculations via Custodian.
Structure
```
from pymatgen.core import Structure
```
Required for defining material structures; often used with atomate workflows.

Quickstart

This quickstart demonstrates how to define a basic VASP static energy workflow using atomate. It requires `pymatgen` for structure definition and outputs a `FireWorks.Workflow` object. To actually execute this workflow, you will need a properly configured FireWorks environment, a running MongoDB instance, and the VASP executable accessible on your system. The `vasp_cmd` and `db_file` parameters are critical for job execution and result storage.

import os
from atomate.vasp.workflows.base import wf_static
from pymatgen.core import Structure

# Define a simple structure for a quick example
structure = Structure(
    lattice=[[3, 0, 0], [0, 3, 0], [0, 0, 3]],
    species=["Fe", "O"],
    coords=[[0, 0, 0], [0.5, 0.5, 0.5]]
)

# Set VASP command and database file path from environment variables if available
# These are crucial for running actual simulations.
vasp_cmd = os.environ.get('VASP_CMD', 'vasp_std') # Default to 'vasp_std' if not set
db_file = os.environ.get('ATOMATE_DB_FILE', None) # If None, atomate looks for default FireWorks config

# Create a static energy workflow for this structure
# Note: This code *defines* the workflow; running it requires FireWorks setup,
# a VASP executable, and a MongoDB database.
workflow = wf_static(
    structure=structure,
    vasp_cmd=vasp_cmd,
    db_file=db_file
)

print(f"Successfully created atomate workflow: {workflow.name}")
print(f"This workflow contains {len(workflow.fws)} FireWorks.")
print("To run, ensure FireWorks is configured (FW_CONFIG_FILE), MongoDB is running, and VASP is accessible.")
# Example of how you would submit (requires FireWorks LaunchPad setup):
# from fireworks import LaunchPad
# lpad = LaunchPad.auto_load()
# lpad.add_wf(workflow)
# print("Workflow added to LaunchPad. Use 'lpad_launch --nlaunches 1' to start.")

view raw JSON →