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. It 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.
gedent
stands for gerador de entradas, which is the portuguese translation
for input generator. 🇧🇷
Before installing gedent
, ensure that you have the following prerequisites:
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
From crates.io
This is the preferred method of installation.
gedent
can be installed by issuing the following command:
cargo install gedent
After, run gedent --set-up
to conveniently create a configuration directory,
and populate it with some base templates, presets and a configuration.
To install gedent
from source 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 set up gedent. That is made easy
by the --set-up
flag. After installing gedent, simply run gedent --set-up
and the configuration will be done for you. You can check if the config and the
templates are fine by the --health
flag.
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.
In gedent
, templates play a central role in generating the inputs. The
template
subcommand facilitates template management.
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.
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):
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.
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.
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"]
Let's walk through an example using gedent
to generate an input file for
optimizing a water molecule with Orca.
-
Create a New Template:
gedent template new opt orca
This command generates a new template named
opt
based on theorca
preset and opens the file in your default editor. -
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) }} *
-
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
-
Adjust Configuration: If needed, modify the configuration using:
gedent config set
-
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 *
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.
For quick access to command summaries and options, utilize the --help
flag.
For example:
gedent --help
gedent template --help
gedent gen --help
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.
gedent
was built on top of the following amazing crates:
gedent
is released under the MIT License.