Metadata-Version: 2.4
Name: molorient
Version: 0.1.0b1
Summary: Aligns molecules with a standardized axis system.
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: periodictable>=2.1.0
Dynamic: license-file

# MolOrient

In computational chemistry *molecules* are sets of *atoms* where each atom is
often represented by a point in a three-dimensional Cartesian space. The
coordinates for each atom ultimately depend on the definition of the axis
system, including the distance and relative orientation with respect to the
molecule. For many problems, what matters is not the absolute Cartesian
coordinates of the atoms, but rather their relative positions, i.e., the
distances and angles among them. Since the relative positions of the atoms
are invariant to a translation and rotation of the axis system, this means that
Cartesian coordinates do **NOT** define a unique representation of the molecule.

The lack of uniqueness, complicates:

- using molecules as data descriptors such as in machine learning
- uniquely defining integration grids for density functional theory
- standardizing direction-dependent properties such as multipole moments,
  polarizabilities, etc.
- assigning symmetry labels
- reusing/restarting calculations (need to know how the intermediate quantities
  are oriented)
- comparing structures

One solution is to standardize the axis system. **MolOrient** is a Python
package for aligning molecules with a standardized axis systems.

## Features

- Completely reproducible orientation standardization. MolOrient relies on
  arbitrary-length fixed-precision arithmetic to ensure results contain a user-
  specified number of significant figures.
- Built-in support for Standard Nuclear Orientation, as well as NWChem's
  standard orientation.
- Easy to add other standards.

## Installation

MolOrient is on the Python Package Index, so installation is straightforward.

```Bash
pip install molorient
```

## Example Usage

### Standard Nuclear Orientation (SNO)

MolOrient reads a molecule in `.xyz` format and does not accept other chemical
file formats. For example, `water.xyz`:

```text
3
Water
O 0.0000000 0.0000000 0.1168520
H 0.0000000 0.7546680 -0.4674100
H 0.0000000 -0.7546680 -0.4674100
```

To put it in Standard Nuclear Orientation, run:

```Bash
molorient water.xyz
```

SNO is the default orientation, so `--sno` is optional;
`molorient water.xyz --sno` gives the same result. To change the precision, add
`--precision N`, where N is an integer, otherwise the default is 6 significant
figures. MolOrient will then write the new file as `water_standardized.xyz`.
Here is the result at 6 significant figures:

```text
3
Standardized geometry by MolOrient
O 0.000000 0.116852 0.000000
H -0.754668 -0.467410 0.000000
H 0.754668 -0.467410 0.000000
```

### NWChem Orientation

To use NWChem's orientation, pass the `--nwchem` flag:

```Bash
molorient water.xyz --nwchem
```

MolOrient will, again, write the new file as `water_standardized.xyz`. Here is
the result at 6 significant figures:

```text
3
Standardized geometry by MolOrient (NWChem orientation)
O 0.000000 0.000000 0.116852
H -0.754668 0.000000 -0.467410
H 0.754668 0.000000 -0.467410
```

## Resources

- [Documentation](https://rmrresearch.github.io/molorient/)
- [Contributor Guidelines](https://github.com/rmrresearch/molorient/blob/main/.github/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/rmrresearch/molorient/blob/main/.github/CODE_OF_CONDUCT.md)

## Acknowledgments

Work at the Ames National Laboratory was supported by the U.S. Department of
Energy Office of Science, Science Undergraduate Laboratory Internships (SULI)
program under its contract with Iowa State University, Contract No.
DE-AC02-07CH11358. John Lewis is grateful to the DOE for the assistantship and
for the opportunity to participate in the SULI program.
