Simulations
FHI-aims
Run ab initio calculations using the FHI-aims electronic structure code.
1. Overview
Atomic Tessellator provides first-class support for the FHI-aims DFT calculator. FHI-aims is a quantum mechanical simulation package for materials science calculations that performs ab initio density functional theory (DFT) calculations.
You can find the complete FHI-aims manual here.
2. Preparing FHI-aims Simulations
All FHI-aims simulations require both control.in and geometry.in files that define the calculation parameters and atomic structure respectively.
You can use the sample H2O relaxation template below to get started with the FHI-aims integration.
Note: If using a GPU cluster, ensure that your control.in file sets use_gpu=true.
control.in
#########################################################################################
#
# Volker Blum, 2017 : Test run input file control.in for simple H2O
#
#########################################################################################
#
# Physical model
#
xc pbe
spin none
relativistic none
charge 0.
#
# Relaxation
#
relax_geometry bfgs 1.e-2
#
################################################################################
#
# FHI-aims code project
# VB, Fritz-Haber Institut, 2009
#
# Suggested "light" defaults for H atom (to be pasted into control.in file)
# Be sure to double-check any results obtained with these settings for post-processing,
# e.g., with the "tight" defaults and larger basis sets.
#
################################################################################
species H
# global species definitions
nucleus 1
mass 1.00794
#
l_hartree 4
#
cut_pot 3.5 1.5 1.0
basis_dep_cutoff 1e-4
#
radial_base 24 5.0
radial_multiplier 1
angular_grids specified
division 0.2421 50
division 0.3822 110
division 0.4799 194
division 0.5341 302
# division 0.5626 434
# division 0.5922 590
# division 0.6542 770
# division 0.6868 1202
# outer_grid 770
outer_grid 302
################################################################################
#
# Definition of "minimal" basis
#
################################################################################
# valence basis states
valence 1 s 1.
# ion occupancy
ion_occ 1 s 0.5
################################################################################
#
# Suggested additional basis functions. For production calculations,
# uncomment them one after another (the most important basis functions are
# listed first).
#
# Basis constructed for dimers: 0.5 A, 0.7 A, 1.0 A, 1.5 A, 2.5 A
#
################################################################################
# "First tier" - improvements: -1014.90 meV to -62.69 meV
hydro 2 s 2.1
hydro 2 p 3.5
# "Second tier" - improvements: -12.89 meV to -1.83 meV
# hydro 1 s 0.85
# hydro 2 p 3.7
# hydro 2 s 1.2
# hydro 3 d 7
# "Third tier" - improvements: -0.25 meV to -0.12 meV
# hydro 4 f 11.2
# hydro 3 p 4.8
# hydro 4 d 9
# hydro 3 s 3.2
################################################################################
#
# FHI-aims code project
# VB, Fritz-Haber Institut, 2009
#
# Suggested "light" defaults for O atom (to be pasted into control.in file)
# Be sure to double-check any results obtained with these settings for post-processing,
# e.g., with the "tight" defaults and larger basis sets.
#
################################################################################
species O
# global species definitions
nucleus 8
mass 15.9994
#
l_hartree 4
#
cut_pot 3.5 1.5 1.0
basis_dep_cutoff 1e-4
#
radial_base 36 5.0
radial_multiplier 1
angular_grids specified
division 0.2659 50
division 0.4451 110
division 0.6052 194
division 0.7543 302
# division 0.8014 434
# division 0.8507 590
# division 0.8762 770
# division 0.9023 974
# division 1.2339 1202
# outer_grid 974
outer_grid 302
################################################################################
#
# Definition of "minimal" basis
#
################################################################################
# valence basis states
valence 2 s 2.
valence 2 p 4.
# ion occupancy
ion_occ 2 s 1.
ion_occ 2 p 3.
################################################################################
#
# Suggested additional basis functions. For production calculations,
# uncomment them one after another (the most important basis functions are
# listed first).
#
# Constructed for dimers: 1.0 A, 1.208 A, 1.5 A, 2.0 A, 3.0 A
#
################################################################################
# "First tier" - improvements: -699.05 meV to -159.38 meV
hydro 2 p 1.8
hydro 3 d 7.6
hydro 3 s 6.4
# "Second tier" - improvements: -49.91 meV to -5.39 meV
# hydro 4 f 11.6
# hydro 3 p 6.2
# hydro 3 d 5.6
# hydro 5 g 17.6
# hydro 1 s 0.75
# "Third tier" - improvements: -2.83 meV to -0.50 meV
# ionic 2 p auto
# hydro 4 f 10.8
# hydro 4 d 4.7
# hydro 2 s 6.8
# "Fourth tier" - improvements: -0.40 meV to -0.12 meV
# hydro 3 p 5
# hydro 3 s 3.3
# hydro 5 g 15.6
# hydro 4 f 17.6
# hydro 4 d 14
# Further basis functions - -0.08 meV and below
# hydro 3 s 2.1
# hydro 4 d 11.6
# hydro 3 p 16
# hydro 2 s 17.2
geometry.in
# Geometry for water -- needs to be relaxed as the water molecule
# described here has a 90degree bond angle and a
# 1 Angstrom bond distance ...
atom 0.00000000 0.00000000 0.00000000 O
atom 0.70700000 -0.70700000 0.00000000 H
atom -0.70700000 -0.70700000 0.00000000 H
3. Creating FHI-aims Simulations
3.1. Basic Simulation Creation
Create a new FHI-aims calculation with control and geometry files:
aims.py
# Read control.in file contents
with open('/path/to/control.in', 'r') as f:
control_file = f.read()
# Read geometry.in file contents
with open('/path/to/geometry.in', 'r') as f:
geometry_file = f.read()
# Create the simulation
result = fhi_aims.create_simulation(
project_id=project_id,
control_file=control_file,
geometry_file=geometry_file,
action="DRAFT",
name="H2O DFT Relax Calculation",
description="Basic DFT Relax for H2O",
extra_simulation_kwargs={
"selected_cluster": cluster_id
}
)
3.2. Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | str | Yes | Target project ID where the simulation will be created |
control_file | str | Yes | Complete contents of the control.in file |
geometry_file | str | Yes | Complete contents of the geometry.in file |
action | str | Yes | Either "DRAFT" (save without running) or "LAUNCH" (submit for execution) |
name | str | No | Human-readable name for the simulation |
description | str | No | Optional description of the simulation |
extra_simulation_kwargs | dict | No | Additional parameters including cluster selection |
4. Retrieving Simulations
Retrieve complete simulation information by ID.
aims.py
simulation = fhi_aims.get_simulation("simulation_id")
print(f"Name: {simulation['name']}")
print(f"Status: {simulation['task']['status']}")
print(f"Control file: {simulation['control_file'][:100]}...")
print(f"Geometry file: {simulation['geometry_file'][:100]}...")
You can also expand query parameters:
aims.py
# Get simulation with specific fields
simulation = fhi_aims.get_simulation(
simulation_id="simulation_id",
expand="task"
)
5. File Management
Link user-uploaded files to FHI-aims simulations:
aims.py
# Associate a file with the simulation
association = fhi_aims.associate_user_upload_with_fhiaims_simulation(
user_upload_id="your-upload-id",
fhi_simulation_id="simulation_id"
)
print(f"Associated file: {association}")
Retrieve all files linked to a simulation:
aims.py
files = fhi_aims.get_simulation_files("simulation_id")
for file_assoc in files['results']:
filename = file_assoc['user_upload']['filename']
print(f" - {filename}")
6. Simulation Management
Remove simulations from your project:
aims.py
result = fhi_aims.delete_simulation("simulation_id")