Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Finish basic documentation #23

Merged
merged 8 commits into from
Jan 17, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
296 changes: 280 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,298 @@
# gedent

Gedent is an input generator for computational chemistry workflows.
`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.

As the needs for molecular dynamics software is much more diverse, gedent does
not aim to provide capabilites for this kind of software.
`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 though with this
`gedent` aims to provide a paradigm of configurations and templates for software
such as [XTB](https://xtb-docs.readthedocs.io/en/latest/),
[orca](https://www.faccts.de/orca/),
[ADF](https://www.scm.com/),
[Gaussian](https://gaussian.com/),
[NWChem](https://www.nwchem-sw.org/)
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
functionalities that support your needs.
features that support your needs.

## Is it any good?

[Yes.](https://news.ycombinator.com/item?id=3067434)

## Installation

### Requirements

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

- [Rust](https://www.rust-lang.org/tools/install) (version 1.65.0 or later)
- [Cargo](https://doc.rust-lang.org/cargo/), the Rust package manager

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

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

### Installing from [crates.io](https://crates.io/crates/gedent)

Once Rust and Cargo are in place, `gedent` can be installed from [crates.io](https://crates.io/) using Cargo:

```bash
cargo install gedent
```

This command downloads necessary dependencies, compiles the `gedent` binary, and installs it on your system.

### Directly from [GitHub](https://github.com/caprilesport/gedent)

Alternatively,
you can install `gedent` directly from the GitHub repository
using Cargo by running:

```bash
cargo install --git=https://github.com/caprilesport/gedent.git
```

### By cloning the GitHub repository

You can also build `gedent` from source by cloning the GitHub repository
and running `cargo build`:

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

After building,
the binary will be located at `target/release/gedent`.


## Configuration

gedent offers support for a per-project configuration file, it searches previous
directories (until the user home folder) and if no config is found it uses the
default config location (~/.config/gedent).
The config file accepts any keys, and is user defined. A default config
file is provided by gedent with sane defaults for XTB and orca (for now).
`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:

```bash
gedent init
```

Pairing the user defined config file with the power of [TERA templates]()
Pairing the user defined config file with the power of [TERA templates](https://keats.github.io/tera/)
gives rise to a rich system of input generation.

## Templates
Here is an example configuration for `gedent`:

```toml
[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](https://keats.github.io/tera/docs/#getting-started).It is heavily based on the [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/)
and [Django](https://docs.djangoproject.com/en/5.0/ref/templates/language/)
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:

```bash
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](https://github.com/caprilesport/gedent/issues/new)):
- [orca](https://www.faccts.de/orca/)
- [ADF](https://www.scm.com/)
- [Gaussian](https://gaussian.com/)
- [NWChem](https://www.nwchem-sw.org/)

#### 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:

```toml
--@
extension = "inp"
--@
```

The metadata uses [TOML](https://toml.io/en/) syntax.


### Template rendering

`gedent` renders templates using the `.xyz` format, and users can leverage [openbabel](https://openbabel.org/) for format conversion if needed. Generating an input file is straightforward:

```bash
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](https://keats.github.io/tera/docs/#built-in-functions) and [filters](https://keats.github.io/tera/docs/#built-in-filters) two additional functions that receive a Molecule are provided, `print_molecule` and `split_molecule`.

Example `Molecule` object fields:

```bash
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](https://www.faccts.de/orca/).

1. **Create a New Template:**
```bash
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:

```bash
--@
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:
```bash
gedent config print
```


Which will print something like this:

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

4. **Adjust Configuration:**
If needed, modify the configuration using:
```bash
gedent config set
```

5. **Generate Optimization Input:**
```bash
gedent gen opt h2o.xyz
```
This generates the optimization input based on the template and specified XYZ coordinates.


Which yields:

```bash
! 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](./templates) or the [presets](./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:

```bash
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](https://github.com/caprilesport/gedent/issues/new)
or [a pull request](https://github.com/caprilesport/gedent/pulls).

## Acknowledgments

`gedent` was built on top of the following amazing crates:

- [TERA](https://github.com/Keats/tera)
- [Dialoguer](https://github.com/console-rs/dialoguer)

## License

`gedent` is released under the [MIT License](LICENSE).

## Examples

3 changes: 3 additions & 0 deletions presets/adf
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
--@
extension = "run"
--@
AMS_JOBNAME={{ molecule.filename }} $AMSBIN/ams <<eor

Task SinglePoint
Expand Down
3 changes: 3 additions & 0 deletions presets/gaussian
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
--@
extension = "gjf"
--@
%nproc={{ nprocs }}
%mem={{ memory }}
# {{ dft_level }}/{{ dft_basis_set }} opt freq=noraman scrf=(smd, solvent={{ solvent }})
Expand Down
3 changes: 3 additions & 0 deletions presets/nwchem
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
--@
extension = ""
--@
title "{{ molecule.filename }}"
geometry
{{ print_molecule(molecule=molecule) }}
Expand Down