Modular computation tool chain library

Installation

To build this project from the source code in this repository you need to have a Fortran compiler supporting Fortran 2008 and one of the supported build systems:

meson version 0.55 or newer, with a build-system backend, i.e. ninja version 1.7 or newer
cmake version 3.14 or newer, with a build-system backend, i.e. ninja version 1.10 or newer
fpm version 0.3.0 or newer

Currently this project supports GCC, Intel and PGI/NVHPC compilers.

Building with meson

Setup a build with

meson setup _build

You can select the Fortran compiler by the FC environment variable. To compile the project run

meson compile -C _build

You can run the projects testsuite with

meson test -C _build --print-errorlogs

To include mctc-lib in your project add the following wrap file to your subprojects directory:

[wrap-git]
directory = mctc-lib
url = https://github.com/grimme-lab/mctc-lib
revision = head

You can retrieve the dependency from the wrap fallback with

mctc_dep = dependency('mctc-lib', fallback: ['mctc-lib', 'mctc_dep'])

and add it as dependency to your targets.

Building with CMake

Alternatively, this project can be build with CMake (in this case ninja 1.10 or newer is required):

cmake -B _build -G Ninja

To compile the project with CMake run

cmake --build _build

You can run the project testsuite with

pushd _build && ctest && popd

To include mctc-lib in your CMake project retrieve it using the FetchContent module:

if(NOT TARGET mctc-lib)
  set("mctc-lib-url" "https://github.com/grimme-lab/mctc-lib")
  message(STATUS "Retrieving mctc-lib from ${mctc-lib-url}")
  include(FetchContent)
  FetchContent_Declare(
    "mctc-lib"
    GIT_REPOSITORY "${mctc-lib-url}"
    GIT_TAG "HEAD"
  )
  FetchContent_MakeAvailable("mctc-lib")
endif()

And link against the "mctc-lib" interface library.

target_link_libraries("${PROJECT_NAME}-lib" PUBLIC "mctc-lib")

Building with fpm

Invoke fpm in the project root with

fpm build

To run the testsuite use

fpm test

You can access the mctc-convert program using the run subcommand

fpm run -- --help

To use mctc-lib for testing include it as dependency in your package manifest

[dependencies]
mctc-lib.git = "https://github.com/grimme-lab/mctc-lib"

Example

An example application is provided with the mctc-convert program to convert between different supported input formats.

To read an input file using the IO library use the read_structure routine. The final geometry data is stored in a structure_type:

use mctc_io
use mctc_env
type(structure_type) :: mol
type(error_type), allocatable :: error

call read_structure(mol, "input.xyz", error)
if (allocated(error)) then
   print '(a)', error%message
   error stop
end if

The environment library provides a basic error back-propagation mechanism using an allocatable error_type, which is passed to the library routines. Usually the reader can detect the file type from the suffix of file names. Alternatively, the filetype enumerator provides the identifiers of all supported file types, which can be passed as optional argument to the read_structure routine.

In a similar way the write_structure routine allows to write a structure_type to a file or unit:

use mctc_io
use mctc_env
type(structure_type) :: mol
type(error_type), allocatable :: error

call write_structure(mol, "output.xyz", error)
if (allocated(error)) then
   print '(a)', error%message
   error stop
end if

The mctc-convert program provides a chained reader and writer call to act as a geometry file converter. Checkout the implementation in app/main.f90.

Error reporting

The geometry input readers try to be provide helpful error messages, no user should be left alone with an error message like invalid input. Unclear error messages are considered a bug in mctc-lib, if you struggle to make sense of a reported error, file us an issue and we will make the report better.

How can helpful error messages look like? Here are some examples.

negative number of atoms declared in xyz file

Error: Impossible number of atoms provided
 --> struc.xyz:1:1-2
  |
1 | -3
  | ^^ expected positive integer value
  |

total charge is not specified as integer

Error: Cannot read eht entry
  --> struc.coord:18:13-15
   |
18 | $eht charge=one unpaired=0
   |             ^^^ expected integer value
   |

a fixed width entry contains an incorrect value

Error: Cannot read charges
  --> struc.mol:29:23-25
   |
29 | M  CHG  3   1   1   3   b   2  -1
   |                       ^^^ expected integer value
   |

Turbomole input with conflicting data groups

Error: Conflicting lattice and cell groups
  --> struc.coord:37:1-5
   |
35 | $lattice angs
   | -------- lattice first defined here
   :
37 | $cell angs
   | ^^^^^ conflicting cell group
   |

We try to retain as much information as possible when displaying the error message to make it easy to fix the offending part in the input.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “as is” basis, without warranties or conditions of any kind, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.