{"id":9229,"library":"pyocse","title":"Python Organic Crystal Simulation Environment (pyocse)","description":"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.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/MaterSim/pyocse","tags":["materials-science","chemistry","simulation","crystal","force-field","CHARMM","ASE","pymatgen"],"install":[{"cmd":"pip install pyocse","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Atomic Simulation Environment: Core for handling atomic structures and simulations.","package":"ase"},{"reason":"Fundamental library for numerical operations in scientific computing.","package":"numpy"},{"reason":"Scientific computing library, provides optimization, linear algebra, etc.","package":"scipy"},{"reason":"Provides detailed element data and periodic table information.","package":"mendeleev"},{"reason":"Python Materials Genomics: Tools for materials structure analysis and manipulation.","package":"pymatgen"},{"reason":"For displaying progress bars during longer operations.","package":"tqdm"}],"imports":[{"symbol":"Molecule","correct":"from pyocse.data import Molecule"},{"symbol":"Crystal","correct":"from pyocse.crystal import Crystal"},{"symbol":"Builder","correct":"from pyocse.builder import Builder"},{"symbol":"ForceField","correct":"from pyocse.force_field import ForceField"}],"quickstart":{"code":"from pyocse.data import Molecule\nfrom ase.build import molecule as ase_build_molecule\n\n# Create an ASE Atoms object for water\nh2o_ase = ase_build_molecule(\"H2O\")\n\n# Initialize a pyocse Molecule from the ASE object\nmol_h2o = Molecule(ase_atom=h2o_ase, name=\"Water\")\n\nprint(f\"Molecule Name: {mol_h2o.name}\")\nprint(f\"Number of Atoms in pyocse Molecule: {len(mol_h2o.atoms)}\")\nprint(f\"Atom symbols: {[atom.symbol for atom in mol_h2o.atoms]}\")\n\n# Access the underlying ASE Atoms object for ASE-specific methods\nif mol_h2o.ase_atom:\n    print(f\"Positions of first atom (via ASE): {mol_h2o.ase_atom.get_positions()[0]}\")\nelse:\n    print(\"Underlying ASE Atoms object not available.\")","lang":"python","description":"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."},"warnings":[{"fix":"Consult the v0.1.0 release notes and updated examples in the documentation for the current usage patterns of `pyocse.force_field`.","message":"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.","severity":"breaking","affected_versions":"<0.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install pyocse` in your terminal to install the library.","cause":"The `pyocse` library has not been installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'pyocse'"},{"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.","cause":"The constructor for `pyocse.data.Molecule` or `pyocse.crystal.Crystal` received `None` for an argument that explicitly expects an `ase.Atoms` object.","error":"TypeError: Argument 'ase_atom' must be an ase.Atoms object, not NoneType"},{"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.","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.","error":"AttributeError: 'Molecule' object has no attribute 'get_cell'"}]}