H2MOF

Code for the study Predicting Hydrogen Storage in MOFs: Representation Matters.

H2MOF benchmarks geometric descriptors, energy voxels, and molecular point clouds for predicting hydrogen adsorption in metal-organic frameworks.

Installation

Requires Python >= 3.10.

pip install -e .

Expected Data Layout

By default, the pipeline looks for these files at the repository root:

• hmof_data.csv: labels indexed by MOF_name
• train.json, validation.json, test.json: dataset splits
• hmof_voxels/<MOF_name>.npy: voxel representations
• hmof_point_clouds/<MOF_name>.npy: point-cloud representations

These paths can be overridden through CLI flags or environment variables where supported.

Typical Workflow

1. Build labels from MOFX-DB JSON files:

h2mof labels --input-dir hmof_json --output-csv hmof_data.csv

Input files are expected as hMOF-*.json and optionally tobmof-*.json.

2. Generate representation assets:

# Energy voxels
moxel hmof_cif hmof_voxels --grid_size 25 --cutoff 10 --epsilon 50 --sigma 2.5

# Point clouds
aidsorb create hmof_cif --outname hmof_point_clouds

3. Create train/validation/test splits:

aidsorb prepare hmof_point_clouds --split_ratio "(0.8, 0.1, 0.1)"

4. Run the benchmark suite:

h2mof bench

Main Commands

Use h2mof <command> --help for full details.

h2mof labels
h2mof bench
h2mof curves
h2mof eval-external

• h2mof bench: trains and evaluates the selected methods on the default split
• h2mof curves: runs the learning-curve experiments
• h2mof eval-external: evaluates trained methods on an external dataset

Outputs

All pipeline commands write to outputs/ by default, or to H2MOF_OUTPUTS_DIR if set.

• outputs/contracts/artifact_schema_version.json
• outputs/models/<method>/<target>/: trained models, predictions, metrics, and run metadata
• outputs/benchmarks/summary_metrics.csv
• outputs/curves/<target>/: learning-curve tables and summaries
• outputs/external/<dataset>/<method>/<target>/: external-evaluation predictions and metrics
• outputs/external/<dataset>/summary/summary_metrics.csv

Environment Variables

• H2MOF_ROOT: override the project root
• H2MOF_OUTPUTS_DIR: override the output directory
• H2MOF_LOG_LEVEL: set console logging level, default INFO
• H2MOF_RICH: set to 0 to disable rich console output
• H2MOF_NUM_WORKERS: DataLoader workers, default 8

License

This project is released under the MIT License. See LICENSE.