Tutorial simple-adsorption-workflow

Prerequisites

apptainer pull simple-adsorption-workflow.sif oras://gricad-registry.univ-grenoble-alpes.fr/diamond/apptainer/apptainer-singularity-projects/simple-adsorption-workflow.sif:latest

1 - Choose Simulation Parameters

apptainer run simple-adsorption-workflow.sif input

A window with two tabs opens:

saw input gui 1

Select the desired parameters or fill them in manually

saw input gui 3

Modify advanced parameters

saw input gui 2

Save the parameter file

The structures come from the MOFX-DB database based on a server access pointing to the original structural database (CoRE MOF 2019). These structures are cleaned (no solvent, no disorder, etc.) from X-ray diffraction resolved structures from the CSD (Crystallographic Structural Database), where the identifier is a six-letter key.

Currently, partial charges can be determined by two methods:

  • without partial charges: None
  • by charge equilibration EQeq (see this article)

The usable force fields are:

  • ExampleMOFsForceField: a generic force field for MOFs, using a parameter set combining parameters from the Dreiding and UFF force fields.

2 - Run the Simulations

apptainer run simple-adsorption-workflow.sif run -i input.json

The basic script runs as many GCMC simulations using one CPU core each as there are combinations of input parameters. Example: 3 structures x 2 Temperatures x 5 Pressure points x 2 charge methods = 60 simulations.

Note: In its containerized version, the workflow cannot be used with a scheduler, so the user must ensure to launch no more simulations than there are accessible CPU cores to ensure acceptable performance.

The generated file structure is as follows:

.
├── cif
├── gcmc
├── isotherms
├── job_gcmc.sh
├── sim.log
├── zeopp_asa
└── zeopp.log

The adsorption property database is located in the gcmc/run<index>.json file, where <index> is the experiment identifier.

3 - Update the Database

To update a database already generated by a past experiment (e.g., run<index1>.json), a new database can be generated with the command:

apptainer run simple-adsorption-workflow.sif merge -i run<index1>.json run<index>.json -o ./

This results in two new files:

  • run_merged.json: the entire database
  • isotherms.json: the file containing the isotherms

The isotherms.json file does not contain all the metadata for each single-CPU simulation, unlike the run_merged.json file, but it is very useful for grouping data and displaying it simply (see the next section).

4 - Visualize Results

apptainer run simple-adsorption-workflow.sif plot

saw output gui 1

Select the file with the isotherm data

saw output gui 2

saw output gui 3

Visualize the isotherms by selecting the desired parameters