metalquicha

Metalquicha API Documentation

This is the main API documentation landing page generated by FORD. The documentation for comment markup in source code, running FORD and the FORD project file are all maintained on the FORD wiki.

Met’al q’uicha (metalquicha)

Yes, this is AI generated (the image) if you know an artist, please let me know.

Met’al q’uicha (the Huastec (tenek) word for sunflower), which I’ll just write as metalquicha, is a sample quantum chemistry backend with focus on using the pic library and its derivatives: pic-mpi and pic-blas which are Fortran based implementations of commonly used routines such as sorting algorithms, array handling, strings, loggers, timers, etc.

The documentation is hosted at readthedocs, here.

Additionally, users can opt to try the vapaa backend for the mpi_f08 module to ensure cross compiler portability. Please report any issues associated here and in vapaa.

Metalquicha implements a naive backend for unfragmented and fragmented quantum chemistry calculations. Currently, metalquicha uses tblite as its chemistry engine which performs energy calculations.

If you are interested in contributing, please see here. Pic is the main project here and all the contributions fall downstream.

You can see Project for some information on development priorities and things being done!

AI Disclaimer

The development of Metalquicha has been assisted by LLMs, such as ChatGPT, and Claude. The philosophy of “vibe coding” applied to this project is as follows:

• The programmer (Jorge), describes the overall architecture of a subroutine to be implemented and provides pseudocode
• The LLM produces an implementation that compiles
• The programmer writes a unit test for the function and validates the subroutine
• The LLM is asked to optimize the code while keeping the tests passing
• The programmer evaluates the code and evaluates if the routine needs to be redone or just upgraded by hand
• Either the programmer changes the code themselves or if they are lazy or cooking dinner while developing, they ask the LLM to try again

This was applied for routines such as the mqc_finite_difference module, which is pretty trivial to implement.

LLMs were also extensively used to add comments and basic documentation for the code. The idea is that Metalquicha is a platform for development of fragmentation methods aimed to be suitable for everyone - from students with no experience in Fortran and/or Quantum Chemistry to experienced researchers with extensive expertise in both.

Justification for LLM use

I wanted to see to what extent LLMs can be used for Fortran code development. I can conclude that they are actually quite good.

Can I use AI to study and work on this codebase?

Yes. But keep in mind that code reviews will still happen.

Building

You will need an internet connection to download the dependencies. The main dependencies are:

• CMake
• A Fortran compiler
• An MPI installation
• A BLAS/LAPACK install
• TBLITE (will be downloaded automatically)

You can then simply:

mkdir build
cd build
cmake ../
make -j

Notes on Fortran compiler compatibility

If you enable tblite (enabled by default at the moment) you are going to be blocked by which compilers does tblite support. If you decide to not build tblite and just build the framework the code will work with most modern compilers.

Supported compilers:

Using TBlite: gcc, ifx, ifort

Without tblite, i.e. no quantum chemistry: gcc, nvfortran, flang(new), ifx, ifort

Building with the Fortran Package Manager (FPM)

Before executing: The tblite package and some of its dependencies depend on -lblas which is usually not installed, i.e. I use openblas or mkl. You will need to create a symlink to libblas.a. You can do this by knowing where BLAS is installed and doing:

ln -s ${BLAS_ROOT}/lib/libopenblas.a ${LOCAL_BLAS_ROOT}/libblas.a

Then: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LOCAL_BLAS_ROOT

If you don’t do this, then things will not work!

Simply then just do: fpm install --prefix . --compiler mpifort --profile release

Obtaining the FPM

Install the FPM following the instructions and then simply: fpm install

Running a calculation

To run a calculation you need to process the JSON input into our mqc format. To do this, you can simply do:

python mqc_prep.py validation/inputs/prism.json

And this will generate a prism.mqc. Which can be simply run as ./build/mqc validation/inputs/prism.mqc to be run in serial mode. Or mpirun -np 4 ./build/mqc validation/inputs/prism.mqc.

A sample mqc file is shown below:

%schema
name = mqc-frag
version = 1.0
index_base = 0
units = angstrom
end  ! schema

%model
method = XTB-GFN1
basis = cc-pVDZ
aux_basis = cc-pVDZ-RIFIT
end  ! model

%driver
type = Energy
end  ! driver

%structure
charge = 0
multiplicity = 1
end  ! structure

%geometry
3

O 0 0 0.119262
H 0 0.763239 -0.477047
H 0 -0.763239 -0.477047
end  ! geometry

%scf
maxiter = 300
tolerance = 1e-06
end  ! scf

If you don’t want to use the python script, you can modify this file by adding an xyz formatted geometry. Supported calculations are Energy, Gradient, and Hessian.