Skip to content

update documentation #80

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.

Sign up for GitHub

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

Merged
PythonFZ merged 15 commits into from
Nov 15, 2025
Merged

update documentation #80

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f017705
update documentation
PythonFZ Oct 23, 2025
546ad35
update docs
PythonFZ Oct 24, 2025
afd3621
update docs
PythonFZ Oct 24, 2025
08eed70
lint / format
PythonFZ Oct 24, 2025
88153fe
update docs
PythonFZ Nov 5, 2025
8cfa171
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 5, 2025
c8318e3
add auto-detection
PythonFZ Nov 5, 2025
b9b63e6
Merge branch 'update-docs' of https://github.com/zincware/rdkit2ase i…
PythonFZ Nov 5, 2025
93c9cf6
build wheels (#83)
PythonFZ Nov 15, 2025
072edc5
update docs / bump version
PythonFZ Nov 15, 2025
c8c0df9
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 15, 2025
b152a79
fix lint
PythonFZ Nov 15, 2025
de2b25b
Merge branch 'update-docs' of https://github.com/zincware/rdkit2ase i…
PythonFZ Nov 15, 2025
38d6384
update build wheels to actuall run on build
PythonFZ Nov 15, 2025
4960442
add url
PythonFZ Nov 15, 2025
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
539 changes: 331 additions & 208 deletions docs/source/ase_tools.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

380 changes: 244 additions & 136 deletions docs/source/atom_selection.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinxcontrib.mermaid",
]

templates_path = ["_templates"]
Expand Down
140 changes: 128 additions & 12 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,171 @@
molify Documentation
====================

molify provides a bridge between RDKit_ and ASE_.
It further integrates features from Packmol_ and NetworkX_.
**molify** - molecular structure conversion between RDKit, ASE, and NetworkX

The molify package provides tools to convert molecular structures between
RDKit_, ASE_ and NetworkX_.

- RDKit is a versatile and popular cheminformatics library.

- ASE allows interfacing with a wide range of atomistic simulation codes and reads/writes many file formats.

- NetworkX is designed for the creation, manipulation, and study of complex networks.

Key Features
------------

- **Bidirectional conversions** between RDKit Mol, ASE Atoms, and NetworkX Graph objects
- **Connectivity preservation** with automatic bond detection when needed
- **Molecular system building** from SMILES to solvated systems via an additional Packmol_ interface

Conversion Overview
-------------------

These bridging functions are illustrated below.

.. mermaid::

graph LR
A[rdkit.Mol] -->|molify.rdkit2networkx| B[networkx.Graph]
B -->|molify.networkx2ase| C[ase.Atoms]
A -->|molify.rdkit2ase| C

.. mermaid::

graph LR
A[ase.Atoms] -->|molify.ase2networkx| B[networkx.Graph]
B -->|molify.networkx2rdkit| C[rdkit.Mol]
A -->|molify.ase2rdkit| C

Conversion Details
------------------
The rdkit package is built around the concept of molecules, with defined connections, bond orders and charges. Positional information is optional.
In contrast, ASE Atoms objects are built around atomic positions and atomic numbers, with no inherent concept of bonds or connectivity.
NetworkX Graphs are general-purpose graph structures with no predefined chemistry concepts.

To store the connectivity information inside ASE Atoms objects, molify introduces a custom attribute ``ase.Atoms.info['connectivity']``: a list of tuples ``(atom_index_1, atom_index_2, bond_order)`` where indices are 0-based integers and ``bond_order`` can be a float following RDKit convention or None for unknown bond orders.

When connectivity information is not available:

- **ase2networkx**: Uses covalent radii to estimate bonds between atoms.
- **networkx2rdkit**: Uses ``rdkit.Chem.rdDetermineBonds.DetermineBonds`` to determine bond orders from 3D coordinates.


Quick Start
-----------

**Basic Conversions**

We can convert any RDKit molecule to an ASE Atoms object:

.. code-block:: python

import molify
from rdkit import Chem

etoh = Chem.MolFromSmiles("CCO")
etoh = Chem.AddHs(etoh)

atoms = molify.rdkit2ase(etoh)


Likewise, we can convert the ASE Atoms object back to an RDKit molecule:

.. code-block:: python

import molify
import ase.build

nh3 = ase.build.molecule("NH3")
mol = molify.ase2rdkit(nh3)

**NetworkX Conversions**

The networkx.Graph representation can be obtained from either RDKit or ASE objects:

.. code-block:: python

import molify
import ase.build
from rdkit import Chem

etoh_mol = Chem.MolFromSmiles("CCO")
nh3_atoms = ase.build.molecule("NH3")

etoh_graph = molify.rdkit2networkx(etoh_mol)
nh3_graph = molify.ase2networkx(nh3_atoms)


Advanced Features
-----------------

**3D Conformer Generation**

The main functionality of molify is expanded by additional tools that combine multiple packages.
For example, molify provides helper functions to generate 3D conformers directly from SMILES strings and store them as ASE Atoms objects.

.. code-block:: python

import molify

# Generate 10 different 3D conformers of water
water = molify.smiles2conformers("O", numConfs=10)


**Molecular System Building**

For many applications, it is useful to solvate molecules or create mixtures.
molify provides a convenient interface to Packmol_ for building molecular systems.

.. code-block:: python

import molify

# Generate conformers for water and ethanol
water = molify.smiles2conformers("O", numConfs=10)
etoh = molify.smiles2conformers("CCO", numConfs=10)

# Pack 5 water and 5 ethanol molecules into a box at 800 kg/m³
# Note: Requires Packmol.jl (Julia) or Packmol to be installed
box = molify.pack(
data=[water, etoh], counts=[5, 5], density=800, packmol="packmol.jl"
)
Comment on lines +113 to 135

@coderabbitai coderabbitai Bot Nov 5, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify Advanced Features functions and documentation links.

The Advanced Features section references molify.smiles2conformers() and molify.pack() functions. Verify these are exported in the public API and that the documentation link targets (:doc:packmol_tools, :doc:ase_tools, etc. on line 135) exist and resolve correctly during documentation build.

Run the following script to verify function exports and documentation references:

🏁 Script executed:

#!/bin/bash
# Description: Verify Advanced Features functions are exported and doc links exist

echo "=== Checking for function definitions ==="
rg -n "def (smiles2conformers|pack)\s*\(" --type py

echo -e "\n=== Checking for referenced documentation files ==="
fd -e rst "^(packmol_tools|ase_tools|rdkit_tools|atom_selection|networkx_tools)\.rst$" docs/source/

Length of output: 168


---

🏁 Script executed:

```shell
#!/bin/bash
# Description: Verify function exports and find actual documentation references

echo "=== Checking molify/__init__.py for function exports ==="
rg -n "smiles2conformers|pack" molify/__init__.py -C 3

echo -e "\n=== Checking index.rst line 135 for documentation link targets ==="
sed -n '135,140p' docs/source/index.rst

echo -e "\n=== Finding all .rst files in docs/source/ ==="
fd -e rst docs/source/ | head -20

Length of output: 296


---

🏁 Script executed:

```shell
#!/bin/bash
# Description: Verify function exports and find actual documentation references

echo "=== Checking molify/__init__.py for function exports ==="
rg -n "smiles2conformers|pack" molify/__init__.py -C 3

echo -e "\n=== Checking index.rst line 135 for documentation link targets ==="
sed -n '135,140p' docs/source/index.rst

echo -e "\n=== Finding all .rst files in docs/source/ ==="
fd -e rst docs/source/

Length of output: 1277


---

🏁 Script executed:

```shell
#!/bin/bash
# Description: Verify documentation link targets exist

echo "=== Finding all .rst files in docs/source/ ==="
fd . docs/source/ -e rst

echo -e "\n=== Checking specifically for referenced doc files ==="
for docname in packmol_tools ase_tools rdkit_tools atom_selection networkx_tools; do
  if [ -f "docs/source/${docname}.rst" ]; then
    echo "✓ Found: docs/source/${docname}.rst"
  else
    echo "✗ Missing: docs/source/${docname}.rst"
  fi
done

Length of output: 349


---

🏁 Script executed:

```shell
#!/bin/bash
# Description: Check full docs structure and verify this is the issue

echo "=== Full directory structure of docs/ ==="
find docs -type f -name "*.rst" | sort

echo -e "\n=== Check if documentation is incomplete or links are wrong ==="
echo "Searching for any mention of packmol, ase, rdkit in .rst files..."
rg -l "packmol|ase|rdkit" docs/source/

Length of output: 416

Fix broken documentation links in Advanced Features section.

The functions smiles2conformers and pack are correctly exported in the public API. However, the documentation links on line 135 are broken: they reference :doc: targets (which expect .rst files) but the actual documentation files are .ipynb (Jupyter notebooks). The referenced files packmol_tools.rst, ase_tools.rst, rdkit_tools.rst, and atom_selection.rst do not exist; they are named packmol_tools.ipynb, ase_tools.ipynb, etc. This will cause broken links during documentation builds. Update the references to use the correct format (e.g., link to the .ipynb files directly or convert the documentation source files to .rst).

🤖 Prompt for AI Agents 
In docs/source/index.rst around lines 110 to 133 (and the broken link at ~135),
the docs reference non-existent :doc: targets (packmol_tools.rst, ase_tools.rst,
rdkit_tools.rst, atom_selection.rst); update those links to point to the actual
notebook files (packmol_tools.ipynb, ase_tools.ipynb, rdkit_tools.ipynb,
atom_selection.ipynb) or convert the notebooks to .rst and update the targets
accordingly — specifically replace the :doc: references with direct
links/appropriate Sphinx roles that reference the .ipynb files (or change the
source filenames to .rst and keep :doc:) so the documentation builder resolves
them.


mol = molify.ase2rdkit(water[0])
graph = molify.ase2networkx(box)
More details on these tools can be found in the :doc:`packmol_tools`, :doc:`ase_tools`, :doc:`rdkit_tools`, and :doc:`atom_selection` sections.

More examples are provided below.

Installation
------------

**From PyPI**

You can install molify from PyPI:

.. code-block:: console

(.venv) $ pip install molify

From Source
-----------
**From Source**

To install and develop molify from source, we recommend using `uv <https://docs.astral.sh/uv>`_.

More information and installation instructions can be found in the `UV documentation <https://docs.astral.sh/uv/getting-started/installation/>`_.

.. code-block:: console

(.venv) $ git clone https://github.com/zincware/rdkit2ase
(.venv) $ cd rdkit2ase
(.venv) $ git clone https://github.com/zincware/molify
(.venv) $ cd molify
(.venv) $ uv sync
(.venv) $ source .venv/bin/activate

Documentation
-------------

.. toctree::
:maxdepth: 2
:hidden:

ase_tools
rdkit_tools
ase_tools
packmol_tools
networkx_tools
atom_selection
Expand Down
Loading