k1lib.mo module

This module is for all things related to atoms, molecules and their simulations

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.

__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

bonds: List[k1lib.mo.Atom]

List of Atoms bonded to this Atom

property nonHBonds

All bonds this atom has, minus the Hydrogens.

nBonds(atom: k1lib.mo.Atom)

Get number of bonds between this and another atom.

property availableBonds

Available bonds. This includes electron clouds, radical electrons, and Hydrogen bonds.

__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

atoms() → List[k1lib.mo.Atom]

Returns a list of Atoms in the molecule this specific Atom is attached to.

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.

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-.

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()

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()

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.

system() → k1lib.mo.System

Creates a System of the molecule this Atom is attached to.

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

x(a: k1lib.mo.Atom) → torch.Tensor

Get current location vector of the specified Atom.

v(a: k1lib.mo.Atom)

Get current velocity vector of the specified Atom.

animate(xs: List[torch.Tensor], rotateSpeed=0.5)

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

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

plot(x: torch.Tensor = None, ax: matplotlib.axes.Axes = None)

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

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

Simulate system for t steps.

Parameters

• t – simulation total steps

• 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.

k1lib.mo.substances() → List[str]

Get a list of builtin substances. To register new substances, check over Atom.

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

Creates an alkane with n carbons. Example:

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

k1lib.mo.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

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.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.

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

exception k1lib.mo.NoFreeElectrons

Bases: RuntimeError

exception k1lib.mo.OctetFull

Bases: RuntimeError