chempleter 0.1.0b1__tar.gz

chempleter-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Davis Thomas Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chempleter-0.1.0b1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: chempleter
+Version: 0.1.0b1
+Summary: A lightweight generative model that extends SMILES fragments into syntactically valid molecules
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: nicegui>=3.4.1
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pathlib>=1.0.1
+Requires-Dist: rdkit>=2025.9.3
+Requires-Dist: selfies>=2.2.0
+Requires-Dist: torch>=2.9.1
+Requires-Dist: torch>=2.9.1 ; extra == 'cpu'
+Requires-Dist: torch>=2.9.1 ; extra == 'gpu128'
+Requires-Python: >=3.13
+Provides-Extra: cpu
+Provides-Extra: gpu128
+Description-Content-Type: text/markdown
+
+# Chempleter
+
+Chempleter is lightweight generative model which utlises a simple Gated Recurrent Unit (GRU) to predict syntactically valid extensions of a provided molecular fragment.
+It accepts SMILES notation as input and enforces chemical syntax validity using SELFIES for the generated molecules. 
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/davistdaniel/chempleter/main/screenshots/demo.gif" alt="Demo Gif" width="400">
+</div>
+
+
+* Why was Chempleter made?
+    * Mainly for me to get into Pytorch. Also, I find it fun to generate random, possibly unsynthesisable molecules from a starting structure.
+
+* What can Chempleter do?
+    
+    * Currently, Chempleter accepts an intial molecule/molecular fragment in SMILES format and generates a larger molecule with that intial structure included, while respecting chemical syntax. 
+    
+    * It can be used to generate a wide range of structural analogs which the share same core structure (by changing the sampling temperature) or decorate a core scaffold iteratively (by increasing generated token lengths)
+
+    * In the future, it might be adapated to predict structures with a specific chemical property using a regressor to rank predictions and transition towards more "goal-directed" predictions.
+
+
+## Prerequisites
+* Python ">=3.13"
+* See [pyproject.toml](pyproject.toml) for dependencies.
+* [uv](https://docs.astral.sh/uv/) (optional but recommended)
+
+## Get started
+
+
+You can install chempleter using any one of the following ways:
+
+- #### Install from PyPi
+
+    ``python -m pip install chempleter``
+
+    By default, the CPU version of pytorch will be installed. Alternatively, you can install a PyTorch version compatible with your CUDA version by following the [Pytorch documentation](https://pytorch.org/get-started/locally/).
+
+- #### Install using uv
+
+    1. Clone this repo
+
+        ``git clone https://github.com/davistdaniel/chempleter.git``
+
+    2. Inside the project directory, exceute in a terminal:
+
+        ``uv sync``
+
+        By default, the CPU version of pytorch will be installed, in case of using GPU as accelerator and CUDA 12.8:
+
+        ``uv sync --extra gpu128``
+
+        Alternatively, you can install a PyTorch version compatible with your CUDA version by following the [Pytorch documentation](https://pytorch.org/get-started/locally/).
+
+
+    
+
+### Usage
+
+#### GUI
+* To start the Chempleter GUI:
+    
+    ``chempleter-gui``
+
+    or 
+
+    ``uv run src/chempleter/gui.py``
+
+
+* Type in the SMILES notation for the starting structure or leave it empty to generate random molecules. Click on ``GENERATE`` button to generate a molecule.
+* Options:
+    * Temperature : Increasing the temperature would result in more unusual molecules, while lower values would generate more common structures.
+    * Sampling : `Most probable` selects the molecule with the highest likelihood for the given starting structure, producing the same result on repeated generations. `Random` generates a new molecule each time, while still including the input structure.
+
+
+#### As a python library
+
+* To use Chempleter as a python library:
+
+    ```python
+    from chempleter.inference import extend
+    generated_mol, generated_smiles, generated_selfies = extend(smiles="c1ccccc1")
+    print(generated_smiles)
+    >> C1=CC=CC=C1C2=CC=C(CN3C=NC4=CC=CC=C4C3=O)O2
+    ```
+
+    To draw the generated molecule :
+
+    ```python
+    from rdkit import Chem
+    Chem.Draw.MolToImage(generated_mol)
+    ```
+* For details on available parameters, refer to the ``extend`` (``chempleter.inference`` module) function’s docstring.
+
+### Current model performance
+
+Performance metrics were evaluated across 500 independent generations using a model checkpoint trained for 80 epochs with a batch size of 64.
+
+| Metric     | Value | Description                                                                                                  |
+|------------|-------|--------------------------------------------------------------------------------------------------------------|
+| Validity   | 1.0   | Proportion of Generated SMILES which respect chemical syntax; tested using selfies decoder and RDkit parser. |
+| Uniqueness | 0.96  | Proportion of Generated SMILES which were unique                                                             |
+| Novelty    | 0.85  | Proportion of Generated SMILES which were not present in the training datatset                             |
+
+
+### Project structure
+* src/chempleter: Contains python modules relating to different functions.
+* src/chempleter/processor.py: Contains fucntions for processing csv files containing SMILES data and generating training-related files.
+* src/chempleter/dataset.py: ChempleterDataset class
+* src/chempleter/model.py: ChempleterModel class
+* src/chempleter/inference.py: Contains functions for inference
+* src/chempleter/train.py: Contains functions for training
+* src/chempleter/gui.py: Chempleter GUI built using NiceGUI
+* src/chempleter/data :  Contains trained model, vocabulary files
+
+# License
+
+[MIT](https://github.com/davistdaniel/chempleter/tree/main?tab=MIT-1-ov-file#readme) License
+
+Copyright (c) 2025 Davis Thomas Daniel
+
+# Contributing
+
+Any contribution, improvements, feature ideas or bug fixes are always welcome.
+
+## Random Notes
+
+* Training data
+    * QM9 and ZINC datasets. 379997 molecules were used for training in total.
+* Running wihout a GPU
+    * Chempleter uses a 2-layer GRU, it should run comfortably on a CPU.
+
+
+
+
+
+

chempleter-0.1.0b1/README.md

@@ -0,0 +1,137 @@
+# Chempleter
+
+Chempleter is lightweight generative model which utlises a simple Gated Recurrent Unit (GRU) to predict syntactically valid extensions of a provided molecular fragment.
+It accepts SMILES notation as input and enforces chemical syntax validity using SELFIES for the generated molecules. 
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/davistdaniel/chempleter/main/screenshots/demo.gif" alt="Demo Gif" width="400">
+</div>
+
+
+* Why was Chempleter made?
+    * Mainly for me to get into Pytorch. Also, I find it fun to generate random, possibly unsynthesisable molecules from a starting structure.
+
+* What can Chempleter do?
+    
+    * Currently, Chempleter accepts an intial molecule/molecular fragment in SMILES format and generates a larger molecule with that intial structure included, while respecting chemical syntax. 
+    
+    * It can be used to generate a wide range of structural analogs which the share same core structure (by changing the sampling temperature) or decorate a core scaffold iteratively (by increasing generated token lengths)
+
+    * In the future, it might be adapated to predict structures with a specific chemical property using a regressor to rank predictions and transition towards more "goal-directed" predictions.
+
+
+## Prerequisites
+* Python ">=3.13"
+* See [pyproject.toml](pyproject.toml) for dependencies.
+* [uv](https://docs.astral.sh/uv/) (optional but recommended)
+
+## Get started
+
+
+You can install chempleter using any one of the following ways:
+
+- #### Install from PyPi
+
+    ``python -m pip install chempleter``
+
+    By default, the CPU version of pytorch will be installed. Alternatively, you can install a PyTorch version compatible with your CUDA version by following the [Pytorch documentation](https://pytorch.org/get-started/locally/).
+
+- #### Install using uv
+
+    1. Clone this repo
+
+        ``git clone https://github.com/davistdaniel/chempleter.git``
+
+    2. Inside the project directory, exceute in a terminal:
+
+        ``uv sync``
+
+        By default, the CPU version of pytorch will be installed, in case of using GPU as accelerator and CUDA 12.8:
+
+        ``uv sync --extra gpu128``
+
+        Alternatively, you can install a PyTorch version compatible with your CUDA version by following the [Pytorch documentation](https://pytorch.org/get-started/locally/).
+
+
+    
+
+### Usage
+
+#### GUI
+* To start the Chempleter GUI:
+    
+    ``chempleter-gui``
+
+    or 
+
+    ``uv run src/chempleter/gui.py``
+
+
+* Type in the SMILES notation for the starting structure or leave it empty to generate random molecules. Click on ``GENERATE`` button to generate a molecule.
+* Options:
+    * Temperature : Increasing the temperature would result in more unusual molecules, while lower values would generate more common structures.
+    * Sampling : `Most probable` selects the molecule with the highest likelihood for the given starting structure, producing the same result on repeated generations. `Random` generates a new molecule each time, while still including the input structure.
+
+
+#### As a python library
+
+* To use Chempleter as a python library:
+
+    ```python
+    from chempleter.inference import extend
+    generated_mol, generated_smiles, generated_selfies = extend(smiles="c1ccccc1")
+    print(generated_smiles)
+    >> C1=CC=CC=C1C2=CC=C(CN3C=NC4=CC=CC=C4C3=O)O2
+    ```
+
+    To draw the generated molecule :
+
+    ```python
+    from rdkit import Chem
+    Chem.Draw.MolToImage(generated_mol)
+    ```
+* For details on available parameters, refer to the ``extend`` (``chempleter.inference`` module) function’s docstring.
+
+### Current model performance
+
+Performance metrics were evaluated across 500 independent generations using a model checkpoint trained for 80 epochs with a batch size of 64.
+
+| Metric     | Value | Description                                                                                                  |
+|------------|-------|--------------------------------------------------------------------------------------------------------------|
+| Validity   | 1.0   | Proportion of Generated SMILES which respect chemical syntax; tested using selfies decoder and RDkit parser. |
+| Uniqueness | 0.96  | Proportion of Generated SMILES which were unique                                                             |
+| Novelty    | 0.85  | Proportion of Generated SMILES which were not present in the training datatset                             |
+
+
+### Project structure
+* src/chempleter: Contains python modules relating to different functions.
+* src/chempleter/processor.py: Contains fucntions for processing csv files containing SMILES data and generating training-related files.
+* src/chempleter/dataset.py: ChempleterDataset class
+* src/chempleter/model.py: ChempleterModel class
+* src/chempleter/inference.py: Contains functions for inference
+* src/chempleter/train.py: Contains functions for training
+* src/chempleter/gui.py: Chempleter GUI built using NiceGUI
+* src/chempleter/data :  Contains trained model, vocabulary files
+
+# License
+
+[MIT](https://github.com/davistdaniel/chempleter/tree/main?tab=MIT-1-ov-file#readme) License
+
+Copyright (c) 2025 Davis Thomas Daniel
+
+# Contributing
+
+Any contribution, improvements, feature ideas or bug fixes are always welcome.
+
+## Random Notes
+
+* Training data
+    * QM9 and ZINC datasets. 379997 molecules were used for training in total.
+* Running wihout a GPU
+    * Chempleter uses a 2-layer GRU, it should run comfortably on a CPU.
+
+
+
+
+
+

chempleter-0.1.0b1/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "chempleter"
+version = "0.1.0b1"
+description = "A lightweight generative model that extends SMILES fragments into syntactically valid molecules"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "nicegui>=3.4.1",
+    "pandas>=2.3.3",
+    "pathlib>=1.0.1",
+    "rdkit>=2025.9.3",
+    "selfies>=2.2.0",
+    "torch>=2.9.1",
+]
+
+classifiers = [
+    "License :: OSI Approved :: MIT License"
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.scripts]
+chempleter-gui = "chempleter.gui:run_chempleter_gui"
+
+[project.optional-dependencies]
+cpu = [
+  "torch>=2.9.1",
+]
+gpu128 = [
+  "torch>=2.9.1",
+]
+
+[tool.uv.sources]
+torch = [
+  { index = "pytorch-cpu" , extra = "cpu"},
+  { index = "pytorch-cu128", extra = "gpu128" },
+]
+
+[tool.uv]
+conflicts = [
+  [
+    { extra = "cpu" },
+    { extra = "gpu128" },
+  ],
+]
+
+[[tool.uv.index]]
+name = "pytorch-cu128"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[build-system]
+requires = ["uv_build>=0.8.8,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv_build]
+src-layout = true
+package-data = {"chempleter" = ["data/*"]}
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.1.0",
+    "jupyter>=1.1.1",
+    "marimo>=0.18.4",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.10",
+    "tqdm>=4.67.1",
+    "twine>=6.2.0",
+]

chempleter-0.1.0b1/src/chempleter/__init__.py

@@ -0,0 +1,31 @@
+# chempleter
+
+__version__ = "0.1.0b1"
+
+from pathlib import Path
+import logging
+
+# logging setup
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(filename)s - %(message)s",
+)
+
+
+def start_experiment(experiment_name, working_dir=None):
+    """
+    Docstring for start_experiment
+
+    :param experiment_name: Description
+    :param working_dir: Description
+    """
+
+    if not working_dir:
+        working_dir = Path().cwd() / experiment_name
+    else:
+        working_dir = Path(working_dir) / experiment_name
+
+    # make dir
+    working_dir.mkdir(parents=True, exist_ok=True)
+
+    return working_dir

chempleter-0.1.0b1/src/chempleter/data/itos.json

@@ -0,0 +1 @@
+["[PAD]", "[START]", "[END]", "[#Branch1]", "[#Branch2]", "[#C]", "[#N+1]", "[#N]", "[-/Ring1]", "[-/Ring2]", "[-\\Ring1]", "[/Br]", "[/C@@H1]", "[/C@@]", "[/C@H1]", "[/C@]", "[/C]", "[/Cl]", "[/F]", "[/N+1]", "[/N-1]", "[/NH1+1]", "[/NH1-1]", "[/NH1]", "[/NH2+1]", "[/N]", "[/O+1]", "[/O-1]", "[/O]", "[/S-1]", "[/S@]", "[/S]", "[=Branch1]", "[=Branch2]", "[=C]", "[=N+1]", "[=N-1]", "[=NH1+1]", "[=NH2+1]", "[=N]", "[=O+1]", "[=OH1+1]", "[=O]", "[=P@@]", "[=P@]", "[=PH2]", "[=P]", "[=Ring1]", "[=Ring2]", "[=S+1]", "[=S@@]", "[=S@]", "[=SH1+1]", "[=S]", "[Br]", "[Branch1]", "[Branch2]", "[C-1]", "[C@@H1]", "[C@@]", "[C@H1]", "[C@]", "[CH1-1]", "[CH2-1]", "[C]", "[Cl]", "[F]", "[I]", "[N+1]", "[N-1]", "[NH1+1]", "[NH1-1]", "[NH1]", "[NH2+1]", "[NH3+1]", "[N]", "[O-1]", "[O]", "[P+1]", "[P@@H1]", "[P@@]", "[P@]", "[PH1+1]", "[PH1]", "[P]", "[Ring1]", "[Ring2]", "[S+1]", "[S-1]", "[S@@+1]", "[S@@]", "[S@]", "[S]", "[\\Br]", "[\\C@@H1]", "[\\C@H1]", "[\\C]", "[\\Cl]", "[\\F]", "[\\I]", "[\\N+1]", "[\\N-1]", "[\\NH1+1]", "[\\NH1]", "[\\NH2+1]", "[\\N]", "[\\O-1]", "[\\O]", "[\\S-1]", "[\\S@]", "[\\S]"]

chempleter-0.1.0b1/src/chempleter/data/stoi.json

@@ -0,0 +1 @@
+{"[PAD]": 0, "[START]": 1, "[END]": 2, "[#Branch1]": 3, "[#Branch2]": 4, "[#C]": 5, "[#N+1]": 6, "[#N]": 7, "[-/Ring1]": 8, "[-/Ring2]": 9, "[-\\Ring1]": 10, "[/Br]": 11, "[/C@@H1]": 12, "[/C@@]": 13, "[/C@H1]": 14, "[/C@]": 15, "[/C]": 16, "[/Cl]": 17, "[/F]": 18, "[/N+1]": 19, "[/N-1]": 20, "[/NH1+1]": 21, "[/NH1-1]": 22, "[/NH1]": 23, "[/NH2+1]": 24, "[/N]": 25, "[/O+1]": 26, "[/O-1]": 27, "[/O]": 28, "[/S-1]": 29, "[/S@]": 30, "[/S]": 31, "[=Branch1]": 32, "[=Branch2]": 33, "[=C]": 34, "[=N+1]": 35, "[=N-1]": 36, "[=NH1+1]": 37, "[=NH2+1]": 38, "[=N]": 39, "[=O+1]": 40, "[=OH1+1]": 41, "[=O]": 42, "[=P@@]": 43, "[=P@]": 44, "[=PH2]": 45, "[=P]": 46, "[=Ring1]": 47, "[=Ring2]": 48, "[=S+1]": 49, "[=S@@]": 50, "[=S@]": 51, "[=SH1+1]": 52, "[=S]": 53, "[Br]": 54, "[Branch1]": 55, "[Branch2]": 56, "[C-1]": 57, "[C@@H1]": 58, "[C@@]": 59, "[C@H1]": 60, "[C@]": 61, "[CH1-1]": 62, "[CH2-1]": 63, "[C]": 64, "[Cl]": 65, "[F]": 66, "[I]": 67, "[N+1]": 68, "[N-1]": 69, "[NH1+1]": 70, "[NH1-1]": 71, "[NH1]": 72, "[NH2+1]": 73, "[NH3+1]": 74, "[N]": 75, "[O-1]": 76, "[O]": 77, "[P+1]": 78, "[P@@H1]": 79, "[P@@]": 80, "[P@]": 81, "[PH1+1]": 82, "[PH1]": 83, "[P]": 84, "[Ring1]": 85, "[Ring2]": 86, "[S+1]": 87, "[S-1]": 88, "[S@@+1]": 89, "[S@@]": 90, "[S@]": 91, "[S]": 92, "[\\Br]": 93, "[\\C@@H1]": 94, "[\\C@H1]": 95, "[\\C]": 96, "[\\Cl]": 97, "[\\F]": 98, "[\\I]": 99, "[\\N+1]": 100, "[\\N-1]": 101, "[\\NH1+1]": 102, "[\\NH1]": 103, "[\\NH2+1]": 104, "[\\N]": 105, "[\\O-1]": 106, "[\\O]": 107, "[\\S-1]": 108, "[\\S@]": 109, "[\\S]": 110}

chempleter-0.1.0b1/src/chempleter/dataset.py

@@ -0,0 +1,82 @@
+import json
+import torch
+import selfies as sf
+import pandas as pd
+from torch.utils.data import Dataset
+from torch.utils.data import DataLoader
+from torch.nn.utils.rnn import pad_sequence
+
+
+class ChempleterDataset(Dataset):
+    """
+    PyTorch Dataset for SELFIES molecular representations.
+
+    :param selfies_file: Path to CSV file containing SELFIES strings in a "selfies" column.
+    :type selfies_file: str
+    :param stoi_file: Path to JSON file mapping SELFIES symbols to integer tokens.
+    :type stoi_file: str
+    :returns: Integer tensor representation of tokenized molecule with dtype=torch.long.
+    :rtype: torch.Tensor
+    """
+
+    def __init__(self, selfies_file, stoi_file):
+        super().__init__()
+        selfies_dataframe = pd.read_csv(selfies_file)
+        self.data = selfies_dataframe["selfies"].to_list()
+        with open(stoi_file) as f:
+            self.selfies_to_integer = json.load(f)
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, index):
+        molecule = self.data[index]
+        symbols_molecule = ["[START]"] + list(sf.split_selfies(molecule)) + ["[END]"]
+        integer_molecule = [
+            self.selfies_to_integer[symbol] for symbol in symbols_molecule
+        ]
+        return torch.tensor(integer_molecule, dtype=torch.long)
+
+
+def collate_fn(batch):
+    """
+    Collate function for a PyTorch DataLoader.
+    Sorts the incoming batch by sequence length in descending order, pads the sequences
+    to the same length (batch_first=True, padding_value=0) using torch.nn.utils.rnn.pad_sequence,
+    and returns the padded batch together with the sorted original lengths.
+    :param batch: Iterable of 1D tensors representing variable-length sequences.
+    :type batch: list[torch.Tensor]
+    :returns: A tuple (padded_batch, tensor_lengths) where padded_batch is a 2D tensor
+              of shape (batch_size, max_seq_len) containing padded sequences, and
+              tensor_lengths is a 1D tensor of original sequence lengths sorted in
+              descending order.
+    :rtype: Tuple[torch.Tensor, torch.Tensor]
+    """
+
+    tensor_lengths = torch.tensor([len(x) for x in batch])
+    tensor_lengths, sorted_idx = tensor_lengths.sort(descending=True)
+    batch = [batch[i] for i in sorted_idx]
+
+    padded_batch = pad_sequence(batch, batch_first=True, padding_value=0)
+
+    return padded_batch, tensor_lengths
+
+
+def get_dataloader(dataset, batch_size=64, shuffle=True, collate_fn=collate_fn):
+    """
+    Create a PyTorch DataLoader.
+
+    :param dataset: PyTorch Dataset instance.
+    :type dataset: torch.utils.data.Dataset
+    :param batch_size: Number of samples per batch.
+    :type batch_size: int
+    :param shuffle: Whether to shuffle the data each epoch.
+    :type shuffle: bool
+    :param collate_fn: Function to merge a list of samples to form a mini-batch.
+    :type collate_fn: callable
+    :return: Configured DataLoader.
+    :rtype: torch.utils.data.DataLoader
+    """
+    return DataLoader(
+        dataset, batch_size=batch_size, shuffle=shuffle, collate_fn=collate_fn
+    )