[!IMPORTANT] gpaw-tools has evolved and is now called Nanoworks! The gpaw-tools project began as a script that utilized only ASE and GPAW. Over the course of four years, it evolved into a comprehensive suite leveraging multiple libraries, including ASAP3, Phonopy, Elastic, OpenKIM, and now modern Machine Learning Potentials (MACE, CHGNet, SevenNet).

Nanoworks

Introduction

Nanoworks is a unified, high-level Python interface for conducting Density Functional Theory (DFT), Molecular Dynamics (MD), and Machine Learning (ML) potential calculations.

It acts as a wrapper and orchestrator for several powerful scientific libraries, making advanced materials simulation accessible through simple command-line tools.

Core Capabilities:

1. DFT (via GPAW & ASE): The dftsolve tool runs PW or LCAO mode calculations. It handles structure optimization, equations of state, elastic tensors, spin-polarized DOS/Band structure, electron densities, phonon calculations, and optical properties (RPA/BSE).
2. MD (via ASAP3 & OpenKIM): The mdsolve tool provides quick geometric optimization and molecular dynamics using interatomic potentials from OpenKIM.
3. ML Potentials (New!): The mlsolve tool enables geometry optimization and static calculations using state-of-the-art Machine Learning Force Fields (MLFF), including MACE, CHGNet, and SevenNet.

Installation

Quick Installation

For Debian/Ubuntu systems, run the automated installation script:

curl -fsSL https://raw.githubusercontent.com/sblisesivdin/nanoworks/refs/heads/main/install_scripts/install-all-Debian-based.sh | bash

Detailed Installation

Prefer a proper and controlled setup? Nanoworks is a Python package. You can install it with pip. However, because you need many other system and Python libraries installed, it is better to refer to the Nanoworks Installation webpage for more detailed installation and usage instructions.

Tools & Usage

After installation, the following commands will be available in your terminal:

1. dftsolve (formerly gpawsolve.py)

The main driver for DFT calculations using GPAW. Uses many cores with -p argument.

Usage:

dftsolve -p <cores> -g <geometry.cif> -i <input.py> 

Usage in auto mode:

dftsolve -p <cores> -g <geometry.cif> -a 

Arguments:

• -g, --geometry: Path to the geometry file (CIF format).
• -i, --input: Path to the Python input file defining calculation parameters.
• -e, --energy: (Optional) Measure energy consumption (Intel CPUs only).
• -v, --version: Version information.
• -p, --parallel: Number of cores to run in parallel.
• -a, --auto: Auto mode. Automatically generate input parameters based on geometry.

2. mdsolve (formerly asapsolve.py)

Perform quick geometric optimizations or MD runs using classical potentials via ASAP3 and OpenKIM.

Usage:

mdsolve -g <geometry.cif> -i <input.py>

Arguments:

• -g, --geometry: Path to the geometry file.
• -i, --input: Path to the input file overriding default parameters (e.g., potential selection).

3. mlsolve (New!)

Run geometry optimizations or static calculations using Machine Learning Force Fields.

Usage:

mlsolve -g <geometry.cif> -i <input.py>

Arguments:

• -g, --geometry: Input geometry file (cif, xyz, POSCAR, etc.).
• -i, --input: Path to the Python input file defining calculation parameters.

Example:

# Optimize a structure using MACE (with parameters in ml_input.py)
mlsolve -g structure.cif -i ml_input.py

Supported Models: mace, chgnet, sevennet.

4. nanoworks

A helper CLI to locate package resources like examples and optimization scripts. For now, it is only showing helpful information. In the future, it will be equipped with more

$ nanoworks
usage: nanoworks [-h] [-v] [--install-examples]

Nanoworks CLI tool

options:
  -h, --help          show this help message and exit
  -v, --version       Show version and detailed library information
  --install-examples  Copy example files to ~/.nanoworks/Examples

5. qeconverter and vaspconverter

Command for creating nanoworks input and geometry files from QE and/or VASP files.

$ qeconverter --input si.scf.in --output-dir example_folder --system-name SiliconQE

$ vaspconverter --poscar POSCAR --incar INCAR --kpoints KPOINTS --output-dir example_folder --system-name Silicon

Helper Scripts

Nanoworks includes several optimization scripts (found via the nanoworks command) to help converge DFT parameters:

• optimize_cutoff.py
• optimize_kpoints.py
• optimize_kptsdensity.py
• optimize_latticeparam.py

Examples

The package includes an examples/ directory covering various scenarios. You can find the location of these examples by running the nanoworks command.

Citing

Please do not forget that Nanoworks is a wrapper/orchestrator software. For the main DFT calculations, it uses ASE and GPAW. It also uses the Elastic Python package for elastic tensor solutions and ASAP with the KIM database for interatomic interaction calculations and Phonopy for the phonon calculations. Therefore, you must know what you use and cite them properly. Here, the basic citation information of each package is given.

ASE

• Ask Hjorth Larsen et al. "The Atomic Simulation Environment—A Python library for working with atoms" J. Phys.: Condens. Matter Vol. 29 273002, 2017.

GPAW

• J. J. Mortensen, L. B. Hansen, and K. W. Jacobsen "Real-space grid implementation of the projector augmented wave method" Phys. Rev. B 71, 035109 (2005) and J. Enkovaara, C. Rostgaard, J. J. Mortensen et al. "Electronic structure calculations with GPAW: a real-space implementation of the projector augmented-wave method" J. Phys.: Condens. Matter 22, 253202 (2010).

KIM

• E. B. Tadmor, R. S. Elliott, J. P. Sethna, R. E. Miller, and C. A. Becker "The Potential of Atomistic Simulations and the Knowledgebase of Interatomic Models" JOM, 63, 17 (2011).

Elastic

• P.T. Jochym, K. Parlinski and M. Sternik "TiC lattice dynamics from ab initio calculations", European Physical Journal B; 10, 9 (1999).

Phonopy

• A. Togo "First-principles Phonon Calculations with Phonopy and Phono3py", Journal of the Physical Society of Japan, 92(1), 012001 (2023).

MACE

• Batatia, Ilyes, et al. "MACE: Higher order equivariant message passing neural networks for fast and accurate force fields." arXiv preprint arXiv:2206.07697 (2022).

CHGNet

• Deng, Bowen, et al. "CHGNet as a pretrained universal graph neural network for charge-informed atomistic modeling." Nature Machine Intelligence 5.9: 1031-1041 (2023).

SevenNet

• Park, Yurum, et al. "SevenNet: A Scalable Equivariant Neural Network for Universal Atomistic Modeling." Journal of Chemical Theory and Computation (2024).

And for Nanoworks usage, please use the following citation:

• B. Sarikavak-Lisesivdin, S.B. Lisesivdin "Nanoworks: A multi-scale python-based orchestrator for materials science simulations" Comput. Condens. Mat. 48, e01362 (2026).

Many other packages need to be cited. With GPAW, you may need to cite LibXC or cite for LCAO, TDDFT, and linear-response calculations. Please visit their pages for many other citation possibilities. For more you can visit https://wiki.fysik.dtu.dk/ase/faq.html#how-should-i-cite-ase, https://wiki.fysik.dtu.dk/gpaw/faq.html#citation-how-should-i-cite-gpaw, and https://openkim.org/how-to-cite/.

Licensing

This project is licensed under the terms of the MIT license.