gedent

gedent is an input generator for computational chemistry workflows. It strives to be simple and as general as possible, while contained in the boundaries of the quantum chemistry research.

gedent stands for gerador de entradas, which is the portugues translation for input generator. 🇧🇷

gedent aims to provide a paradigm of configurations and templates for software such as XTB, orca, ADF, Gaussian, NWChem and similar chemistry software suites. Although it aims to support such software and was thought with this use case in mind, it is a template CLI combined with a user defined configuration, so if you find another use for it, feel free to open a pull request with features that support your needs.

Is it any good?

Yes.

Installation

Requirements

Before installing gedent, ensure that you have the following prerequisites:

• Rust (version 1.65.0 or later)
• Cargo, the Rust package manager

If Rust and Cargo are not already installed, you can conveniently set them up using the following one-liner:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Installation

To install gedent we will build it from source by cloning the GitHub repository and running cargo build:

git clone https://github.com/caprilesport/gedent.git
cd gedent
cargo build --release

After building, the binary will be located at target/release/gedent, to make it available system-wide, you can symlink it to somewhere in your $PATH, e.g.:

sudo ln -s $PWD/target/release/gedent /usr/local/bin

After installing, the only thing left to do is copy the templates and presets directories, as well as the gedent.toml file to your system configuration directory.

Linux and Mac

mkdir ~/.config/gedent
cp -r ./templates ~/.config/gedent/
cp -r ./presets ~/.config/gedent/
cp ./gedent.toml ~/.config/gedent

Configuration

gedent supports per-project configuration files. If no config file (gedent.toml) is found in the current directory or its parent directories, the tool defaults to using the configuration at ~/.config/gedent on Linux.

If you want to modify the parameters in the config just for the current folder (or for any subfolder in it), you can clone the current in-use configuration file by using:

gedent init

Pairing the user defined config file with the power of TERA templates gives rise to a rich system of input generation.

Here is an example configuration for gedent:

[gedent]
default_extension = "gjf"

[parameters]
charge = 1
mult = 1
solvation = true
solvent = "dmso"
random_field = "any valid toml data"
other_named_key = [100, 38, 29]

The [gedent] block contains default settings, and the [parameters] section allows user-defined configurations accessed by templates.

A default config file is provided by gedent with some example defaults for the templates that are shipped with the program.

Templates basics

In gedent, templates play a central role in generating the inputs. The template subcommand facilitates template management.

Getting started

For a comprehensive guide on template capabilities, refer to the Tera templates documentation.It is heavily based on the Jinja2 and Django template languages, so if you know any of these you will feel right at home.

Creating new templates

To create new templates, you can add a base template in the presets directory, then call gedent:

gedent template new "new_template_name"

If no preset name is provided, a fuzzy dialogue box assists in selecting a preset for your new template. The template is then opened in your default editor for modification.

gedent ships with default template presets for popular chemistry software, but users are encouraged to create custom base presets. Right now, we ship the following basic template presets (if your favorite software is not supported, please open a pull-request):

• orca
• ADF
• Gaussian
• NWChem

Template Metadata

Templates support a metadata header using the --@ delimiter. Presently, the only supported metadata is the extension directive, setting the default file extension. Future releases plan to support templates with more than one XYZ file per template.

Example template metadata:

--@
extension = "inp"
--@

The metadata uses TOML syntax.

Template rendering

gedent renders templates using the .xyz format, and users can leverage openbabel for format conversion if needed. Generating an input file is straightforward:

gedent gen `name_of_template` example.xyz

Wildcard support is available, allowing commands like gedent gen orca/opt *.xyz. Use gedent template list to view all available templates.

The molecule object

gedent parses an XYZ file into a Molecule object, which includes the following fields: filename, description, and atoms. On top of the already built-in tera functions and filters two additional functions that receive a Molecule are provided, print_molecule and split_molecule.

Example Molecule object fields:

filename: example
description: Sample XYZ file
atoms: ["O  0.0  0.0  0.0", "H  0.0  1.0  0.0", "H  1.0  0.0  0.0"]

Workflow example

Orca optimization

Let's walk through an example using gedent to generate an input file for optimizing a water molecule with Orca.

1. Create a New Template:

   gedent template new opt orca
   

   This command generates a new template named opt based on the orca preset and opens the file in your default editor.

2. Edit the Template: With the generated template open in your editor, modify it to fit the optimization scenario. For example:

   --@
   extension = "inp"
   --@
   ! {{ functional }} {{ basis_set }}
   ! Opt freq
   
   %pal
    nprocs {{ nprocs }}
   end
   
   %maxcore {{ memory }}
   
   *xyz {{ charge }} {{ mult }}
   {{ print_molecule(molecule = Molecule) }}
   *
   

3. Review Configuration: Ensure the configuration parameters match the requirements. Check the configuration using:

   gedent config print
   

   Which will print something like this:

   charge = 1
   basis_set = "def2svp"
   functional = "BP86"
   functional_class = "GGA"
   memory = 3000
   mult = 1
   nprocs = 8
   solvation = false
   solvent = "water"
   start_hessian = false
   

4. Adjust Configuration: If needed, modify the configuration using:

   gedent config set
   

5. Generate Optimization Input:

   gedent gen opt h2o.xyz
   

   This generates the optimization input based on the template and specified XYZ coordinates.

   Which yields:

   ! BP86 def2svp
   ! Opt freq D3BJ
   
   %pal
    nprocs 8
   end
   
   %maxcore 3000
   
   *xyz 0 1
   O       -0.981036882      0.000000000     -2.282900972
   H       -0.981036882      0.759337000     -1.686857972
   H       -0.981036882     -0.759337000     -1.686857972
   *
   

Example templates

To understand how to create inputs with gedent, explore the shipped templates in the templates directory or the presets. These examples serve as valuable references for creating your custom templates.

Interactive Help

For quick access to command summaries and options, utilize the --help flag. For example:

gedent --help
gedent template --help
gedent gen --help

Contributing

Contributions to gedent are welcome! If you find a bug, have a feature request, or want to contribute code, please open an issue or a pull request.

Acknowledgments

gedent was built on top of the following amazing crates:

• TERA
• Dialoguer

License

gedent is released under the MIT License.