DOCSEARCHbyAlgolia
Submit Docs

SELFIES (Self-Referencing Embedded Strings)

repository·master·Indexed 21 days ago

https://github.com/aspuru-guzik-group/selfies

A robust molecular string representation designed for machine learning and generative models. Unlike SMILES, any SELFIES string can be decoded into a chemically valid molecular graph. The library includes tools for encoding/decoding, semantic constraint configuration for hypervalency, and SMILES attribution tracing. The repository also provides implementations of Variational Autoencoders (VAE) and Generative Adversarial Networks (GAN) for chemistry datasets like QM9.

Tokens
5.9K
Snippets
20
Records
35
Agent score
75%

What's inside SELFIES

  1. Overview of GAN directory structures

    master

    The repository provides two distinct environments for running GANs on the QM9 dataset:

    GAN_selfies

    Used for generating molecules in SELFIES representation.

    • 2RGSMILES_QM9.txt: Dearomatized QM9 dataset in SELFIES format.
    • GAN.py: Main generative adversarial network execution script.
    • one_hot_converter.py: Logic for creating one-hot encodings of molecular strings.
    • adjusted_selfies_fcts.py: SMILES to SELFIES conversion functions.
    • GPlus2S.py: SMILES to SELFIES conversion functions.
    • translate.py: General helper functions.

    GAN_smiles

    Used for generating molecules in SMILES representation.

    • smiles_qm9.txt: Dearomatized QM9 dataset in SMILES format.
    • GAN.py: Main generative adversarial network execution script.
    • one_hot_converter.py: Logic for creating one-hot encodings of molecular strings.

  2. Overview of SELFIES

    master
    SELFIES (SELF-referencIng Embedded Strings) is a 100% robust molecular string representation. Unlike SMILES, SELFIES is designed to be used as direct input for machine learning models—specifically generative models—to ensure that any generated string corresponds to a valid molecular structure with guaranteed validity.

  4. Atomic Symbols in SELFIES

    master

    Atomic symbols follow the form [<B><A>]:

    • <B> is a bond prefix: '' (none), '/', '\', '=', or '#'.
    • <A> is the atom/ion symbol. If the SMILES symbol uses square brackets (e.g., [C@@H]), the brackets are dropped and expl is appended (e.g., C@@Hexpl).

    Bond Multiplicity Logic: An atomic symbol connects atom <A> to the previous atom. If the requested bond multiplicity <B> violates the bond constraints of either the previous or current atom, the multiplicity is automatically reduced to the minimum value required to satisfy all constraints.

    Example 1: [C][=C][C][#C][13Cexpl] -> C=CC#C[13C]
Example 2: [C][F][C][C][C][C] -> CF
Example 3: [C][O][=C][#O][C][F] -> COC=O

  5. How SELFIES derivation works

    master

    SELFIES molecules are derived from a grammar using non-terminal symbols or states $X_0, ext{ldots}, X_7, Q$. Derivation begins at state $X_0$ and proceeds symbol-by-symbol. The process terminates when no non-terminal symbols remain. The state $X_i$ effectively restricts the subsequent bond multiplicity to at most $i$.

    There are three main types of symbols that drive this derivation:

    1. Atomic Symbols: Connect atoms and determine bond multiplicities.
    2. Index Symbols: Determine the size of branches or the location of ring bonds using a hexadecimal encoding.
    3. Branch Symbols: Trigger recursive derivation calls to create molecular branches.

  6. Index Symbols and Hexadecimal Encoding

    master

    Index symbols are used after a ring or branch symbol to derive an integer from the state $Q$. The number of symbols used is determined by the specific ring or branch symbol (e.g., [Ring3] uses the next three symbols).

    Each symbol $s_i$ is mapped to an index via a lookup table. These indices are then treated as hexadecimal (base 16) digits to form the final integer.

    Index Mapping Table:

    IndexSymbolIndexSymbol
    0[C]8[Branch2_3]
    1[Ring1]9[O]
    2[Ring2]10[N]
    3[Branch1_1]11[=N]
    4[Branch1_2]12[=C]
    5[Branch1_3]13[#C]
    6[Branch2_1]14[S]
    7[Branch2_2]15[P]
    All other symbols are assigned index 0.

    Example Calculation: For [Ring3][C][Branch1_1][O], the indices are idx([C])=0, idx([Branch1_1])=3, and idx([O])=9. $Q = (0 \times 16^2) + (3 \times 16^1) + (9 \times 16^0) = 57$.

  7. Understand Ring Symbols in SELFIES

    master

    Ring symbols are used to specify ring bonds between atoms, similar to ring numbering in SMILES. They follow two general forms:

    1. [Ring<L>]: Creates a single bond between the current atom and the $(Q + 1)$-th preceding atom, where <L> is an integer in {1, 2, 3} used to derive the offset $Q$.
    2. [Expl<B>Ring<L>]: Creates a bond of type <B> between the current atom and the $(Q + 1)$-th preceding atom, where <B> is a bond prefix: '/', '\', '=', or '#'.

    Derivation Logic:

    • Ring bonds are typically created in a second pass after all atoms and branches are derived.
    • A ring bond is only created if it does not violate bond constraints.
    • If the current atom is already bonded to the target atom, the bond multiplicity is increased and then reduced minimally to satisfy constraints (up to a maximum multiplicity of 3).

    Examples:

    SELFIES$Q + 1$SMILES
    [C][=C][C][=C][C][=C][Ring1][Branch1_2]5C1=CC=CC=C1
    [C][C][=C][C][=C][C][Expl=Ring1][Branch1_2]5C=1C=CC=CC=1
    [C][C][Expl=Ring1][C]1C#C
    [C][C][C][C][Expl=Ring1][Ring2][Expl#Ring1][Ring2]3, 3C#1CCC#1

  8. Configure semantic constraints for SELFIES

    master

    The SELFIES grammar is derived from semantic constraints that define the maximum bonding capacity for various atoms. By default, atoms like C (4 bonds), N (3 bonds), and O (2 bonds) follow standard valency.

    However, some molecules (e.g., nitrobenzene or chlorate anions) violate these default constraints and cannot be represented. You can customize these constraints using the following functions:

    • get_preset_constraints(): Retrieve predefined constraint sets.
    • get_semantic_constraints(): Retrieve the current semantic constraints.
    • set_semantic_constraints(constraints): Apply a custom set of semantic constraints.

    Warning: SELFIES strings are dependent on the semantic constraints used during encoding. If you use custom constraints, you must record them to ensure reproducibility.

    import selfies

# Example of setting custom constraints if default ones fail for specific molecules
# custom_constraints = ... 
# selfies.set_semantic_constraints(custom_constraints)

  9. Build the documentation locally

    master

    To build the project documentation, you need to install specific Sphinx extensions and then run the Sphinx build command.

    Prerequisites

    Install the following Python packages:

    • sphinx-autodoc-typehints
    • sphinx_rtd_theme
    • nbsphinx

    Build Command

    Run the following command from the repository root, replacing <build-dir> with your desired output directory:

    python -m sphinx source <build-dir>
    python -m sphinx source <build-dir>

  10. Install the SELFIES library

    master

    Install selfies using pip. You can also use pip to check the installed version or upgrade to the latest release.

    # Install selfies
pip install selfies

# Check installed version
pip show selfies

# Upgrade to latest release
pip install selfies --upgrade

  11. Run the Variational Autoencoder (VAE) for Chemistry example

    master

    This example provides an implementation of a Variational Autoencoder (VAE) designed to work with both SMILES and SELFIES representations. It is used to compare these two representations based on reconstruction quality, diversity, and latent space validity.

    To use this example, you will need to interact with the following files:

    • chemistry_vae.py: The core script containing model definitions, data processing, and training logic.
    • settings.yml: The configuration file used to set hyperparameters and toggle the VAE between SMILES and SELFIES modes.
    • data_loader.py: A utility module providing methods to convert SMILES and SELFIES into integer-encoded or one-hot encoded vectors.