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:
objectJust an atom really. Has properties, can bond to other atoms, and can generate a
Systemfor simulation.- __call__(atom: Atom, nBonds: int = 1, main=False) 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
- property availableBonds: int
Available bonds. This includes electron clouds, radical electrons, and Hydrogen bonds.
- bond(atom: Atom, nBonds: int = 1, main=False) 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
- property endChain: Atom
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
- next(offset=0, times: int = 1) 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()andmain(). Check the bonding order withshow().- 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[Atom]
Kinda like
next(), but fetches multiple atoms on the backbone. Example:c1, c2 = mo.CH4(mo.CH4).nexts()
- 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 wherenext()will go next.- Parameters
H – whether to display hydrogens as separate atoms, or bunched into the main atom
- 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) Atom
Creates an alkane with
ncarbons. Example:# returns "C3H8" mo.alkane(3).empirical()
- k1lib.mo.alcohol(n: int, loc: int = 1) Atom
Creates an alcohol with
ncarbons and an OH group at carbonloc. 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, Atom])
Bases:
object- __init__(mapping: Dict[str, 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
Atomobject
- animate(xs: List[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: 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[Tensor]
Simulate system for
tsteps.- 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
recordXsis 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.