k1lib.mo module¶

This module is for everything related to molecules. You can construct, explore and simulate molecules quite easily. Check out the tutorials section for a walkthrough. This is exposed automatically with:

from k1lib.imports import *
mo.C # exposed

class k1lib.mo.Atom(name: str, atomicN: int, massN: float, valenceE: int, radius: List[float] = [], octetE: int = 8)¶

Bases: object

Just an atom really. Has properties, can bond to other atoms, and can generate a System for simulation.

property HBonds¶: All hydrogens this atom is bonded to.

__call__(atom: k1lib.mo.Atom, nBonds: int = 1, main=False) → k1lib.mo.Atom ¶

Forms a bond with another atom. If valence electrons are full, will attempt to disconnect Hydrogens from self to make room.

Parameters

bond – number of bonds. 2 for double, 3 for triple
main – whether to put this bond in front of existing bonds, to signify the “main” chain, so that it works well with next()

Returns

self

__init__(name: str, atomicN: int, massN: float, valenceE: int, radius: List[float] = [], octetE: int = 8)¶

Creates a new atom. Not intended to be used by the end user. If you wish to get a new atom, just do stuff like this:

c1 = mo.C
c2 = mo.C
c1 == c2 # returns False, demonstrating that these are different atoms

If you wish to register new substances with the module, you can do this:

genF = lambda: Atom(...)
mo.registerSubstance("elementName", genF)
mo.elementName # should executes `genF` and returns

Parameters

name – element name (eg. “C”)
atomicN – atomic number (eg. 6)
massN – atomic mass in g/mol (eg. 12)
valenceE – how many valence electrons initially?
radius – covalent radiuses (in pm) for single, double and triple bonds
octetE – how many electrons in a full octet? Default 8, but can be 2 for H and He

atoms() → List[k1lib.mo.Atom]¶: Returns a list of Atoms in the molecule this specific Atom is attached to.

property availableBonds¶: Available bonds. This includes electron clouds, radical electrons, and Hydrogen bonds.

bond(atom: k1lib.mo.Atom, nBonds: int = 1, main=False) → k1lib.mo.Atom ¶: Like __call__(), but returns the atom passed in instead, so you can form the main loop quickly.

property bonds¶: List of Atoms bonded to this Atom

empirical() → str ¶: Returns an empirical formula for the molecule this Atom is attached to.

property endChain¶

Do a bunch of .next() until reached the end of the carbon chain. Example:

c1 = mo.alcohol(3, 1)
c3 = c1.endChain
c3(mo.NH3)
c1.show() # displays in cell

main(atom: k1lib.mo.Atom, nBonds: int = 1) → k1lib.mo.Atom ¶: Like bond(), but with main param defaulted to True.

moveLastCTo2ndC() → k1lib.mo.Atom ¶: Move last carbon to 2nd carbon. Useful in constructing iso- and tert-.

nBonds(atom: k1lib.mo.Atom)¶: Get number of bonds between this and another atom.

next(offset=0, times: int = 1) → k1lib.mo.Atom ¶

Returns the next atom bonded to this. Tries to avoid going into Hydrogens. This is the main way to navigate around the molecule.

You kinda have to make sure that your molecule’s bonding order is appropriate by choosing between bond() and main(). Check the bonding order with show().

Parameters

offset – if there are multiple non-Hydrogen atoms, which ones should I pick?
times – how many times do you want to chain .next()?

nexts(atoms: int = 2) → List[k1lib.mo.Atom]¶

Kinda like next(), but fetches multiple atoms on the backbone. Example:

c1, c2 = mo.CH4(mo.CH4).nexts()

property nonHBonds¶: All atoms this atom is bonded to, minus the Hydrogens.

perfluoro_ize() → k1lib.mo.Atom ¶: Replaces all C-H bonds with C-F bonds

removeBond(atom: k1lib.mo.Atom)¶: Removes all bonds between this and another atom

show(H: bool = True)¶

Show the molecule graph this atom is a part of. Meant for debugging simple substances only, as graphs of big molecules look unwieldy. This also highlights the current Atom, and each bond is an arrow, indicating where next() will go next.

Parameters: H – whether to display hydrogens as separate atoms, or bunched into the main atom

system() → k1lib.mo.System ¶: Creates a System of the molecule this Atom is attached to.

property uniqueBonds¶: All unique bonds. Meaning, if there’s a double bond, only return 1 atom, not 2.

property uniqueNonHBonds¶: All unique non Hydrogen bonds.

k1lib.mo.substances() → List[str]¶: Get a list of builtin substances. To register new substances, check over Atom.

exception k1lib.mo.NoFreeElectrons¶: Bases: RuntimeError

exception k1lib.mo.OctetFull¶: Bases: RuntimeError

k1lib.mo.alkane(n: int) → k1lib.mo.Atom ¶

Creates an alkane with n carbons. Example:

# returns "C3H8"
mo.alkane(3).empirical()

k1lib.mo.alcohol(n: int, loc: int = 1) → k1lib.mo.Atom ¶

Creates an alcohol with n carbons and an OH group at carbon loc. Example:

# returns "C3H8O"
mo.alcohol(3, 1).empirical()

k1lib.mo.sameEmpirical(a: str, b: str) → bool ¶

Checks whether 2 empirical formula are the same or not. Example:

moparse.sameEmpirical("C2H4", "H4C2") # returns True

class k1lib.mo.System(mapping: Dict[str, k1lib.mo.Atom])¶

Bases: object

__init__(mapping: Dict[str, k1lib.mo.Atom])¶

Creates a new system that contains a molecule so that it can be simulated. Not intended to be used by the end user. Use Atom.system() instead.

Parameters: mapping – maps from atom index to Atom object

animate(xs: List[torch.Tensor], rotateSpeed=0.5, H: bool = True)¶

Animates the molecule. This requires location information from simulate(). Example:

s = mo.CH4(mo.H2O).system()
s.animate(s.simulate())

Parameters: H – whether to include Hydrogens as separate atoms or bunched together to another main atom.

plot(x: torch.Tensor = None, ax: matplotlib.axes.Axes = None, H: bool = True)¶

Plots the molecule. Example:

%matplotlib widget
s = mo.CH4(mo.H2O).system()
s.simulate(); s.plot()

The first line is so that you can rotate the molecule around in 3d interactively. The 3rd line includes a simulation step, to get the molecule into roughly the right position.

Parameters

x – location Tensor of shape (n, 3). If none provided, will use current locations
ax – Axes object, in case you want to plot this on an existing plot
H – whether to include Hydrogens as separate atoms or bunched together to another main atom.

simulate(t: int = 300, dt: float = 1.0, recordXs: bool = True, cuda: bool = False) → List[torch.Tensor]¶

Simulate system for t steps.

Parameters

t – simulation total steps. 100 to view dynamics closely, 1000 to make sure it converges, default 300 is sweet spot
dt – simulation time between steps
recordXs – whether to record locations while the simulation happens. Put False to save memory/performance.
cuda – if True, do the simulation on the graphics card

Returns

if recordXs is True, returns max 100 location Tensors. The Tensors will have shape of (n, 3), where n is the number of atoms and electron clouds your molecule has.

v(a: k1lib.mo.Atom)¶: Get current velocity vector of the specified Atom.

x(a: k1lib.mo.Atom) → torch.Tensor ¶: Get current location vector of the specified Atom.

k1lib.mo.parse(s: str, quiet: bool = False) → Union[k1lib.mo.Atom, str]¶: Tries to recognize molecule. Returns molecule Atom if recognized, else the molecule’s string.