Python Organic Crystal Simulation Environment (pyocse)

0.1.3 · active · verified Thu Apr 16

Python Organic Crystal Simulation Environment (pyocse) is a library designed for simulating organic crystals. It facilitates tasks like automated force field generation for CHARMM and handling crystal structures and molecules. The current stable version is 0.1.3, with releases being infrequent, primarily tied to significant feature additions and core updates.

Common errors

```
ModuleNotFoundError: No module named 'pyocse'
```
cause The `pyocse` library has not been installed in the active Python environment.

fix Run `pip install pyocse` in your terminal to install the library.
```
TypeError: Argument 'ase_atom' must be an ase.Atoms object, not NoneType
```
cause The constructor for `pyocse.data.Molecule` or `pyocse.crystal.Crystal` received `None` for an argument that explicitly expects an `ase.Atoms` object.

fix Ensure that the `ase_atom` argument (or similar data input) is provided with a valid `ase.Atoms` instance, or an appropriate alternative like a SMILES string when allowed.
```
AttributeError: 'Molecule' object has no attribute 'get_cell'
```
cause Attempting to call an `ase.Atoms` method (`get_cell` typically for crystals) directly on a `pyocse.data.Molecule` object, which does not directly expose all `ase` methods or may not have a cell attribute.

fix To use `ase`-specific methods or access crystal properties, retrieve the underlying `ase.Atoms` object via the `ase_atom` attribute (e.g., `my_molecule.ase_atom.get_cell()`) or ensure you are operating on a `Crystal` object.

Warnings

breaking The API for automated force field generation was significantly reworked in v0.1.0. Scripts relying on pre-0.1.0 `pyocse.force_field` modules will likely require updates.
Fix: Consult the v0.1.0 release notes and updated examples in the documentation for the current usage patterns of `pyocse.force_field`.
gotcha PyOCSE objects (`Molecule`, `Crystal`) frequently wrap or convert `ase` and `pymatgen` objects. Direct methods from `ase.Atoms` or `pymatgen.Structure` may not be directly available on `pyocse` objects without explicitly accessing their `ase_atom` or `pymatgen_structure` attributes.
Fix: To use `ase` or `pymatgen`-specific methods, access the underlying object via `mol.ase_atom` (or `mol.pymatgen_structure` if applicable) for `Molecule` and similarly for `Crystal`.
gotcha Automated force field generation via `pyocse.force_field` often leverages external services, specifically CHARMM-GUI. This implies a dependency on internet connectivity and the stability/API of the external service, which is outside of `pyocse`'s direct control.
Fix: Ensure a stable internet connection for force field generation. Be aware that changes in CHARMM-GUI's interface could impact `pyocse`'s functionality, potentially requiring updates or adjustments.

Install

pip install pyocse Install stable release

Imports

Molecule
```
from pyocse.data import Molecule
```
Crystal
```
from pyocse.crystal import Crystal
```
Builder
```
from pyocse.builder import Builder
```

ForceField

from pyocse.force_field import ForceField

Quickstart

This quickstart demonstrates how to initialize a `pyocse.data.Molecule` object, specifically by converting an `ase.Atoms` object. It then shows how to access basic molecular properties and interact with the underlying `ase` object for more detailed atomic manipulation, highlighting the interoperability.

from pyocse.data import Molecule
from ase.build import molecule as ase_build_molecule

# Create an ASE Atoms object for water
h2o_ase = ase_build_molecule("H2O")

# Initialize a pyocse Molecule from the ASE object
mol_h2o = Molecule(ase_atom=h2o_ase, name="Water")

print(f"Molecule Name: {mol_h2o.name}")
print(f"Number of Atoms in pyocse Molecule: {len(mol_h2o.atoms)}")
print(f"Atom symbols: {[atom.symbol for atom in mol_h2o.atoms]}")

# Access the underlying ASE Atoms object for ASE-specific methods
if mol_h2o.ase_atom:
    print(f"Positions of first atom (via ASE): {mol_h2o.ase_atom.get_positions()[0]}")
else:
    print("Underlying ASE Atoms object not available.")

view raw JSON →