----------------------------------------------------------------------
This is the API documentation for the tetramol library.
----------------------------------------------------------------------


## Classes

Core classes


Builder(up: ArrayLike = (0.0, 0.0, 1.0), left: ArrayLike = (-1.0, 0.0, 0.0), *, xh_length: float = 1.1, xy_length: float = 1.5) -> None

Build a molecule atom by atom on a tetrahedral grid.

Every atom has four bond slots, one per direction of the
`tetrahedral_basis`. Bonded atoms have opposite parities: an atom of parity
+1 bonds along the basis directions, and one of parity -1 along their
negatives. A child added through slot ``i`` therefore bonds back to its
parent through its own slot ``i``. Filling in carbons gives the diamond
lattice, and neighboring centers are always staggered.

Example:
    A C-N bond pointing up, with a methyl group to the left of the carbon:

    >>> b = Builder(up=(0, 0, 1), left=(-1, 0, 0))
    >>> c = b.add("C")
    >>> n = b.add("N", c, toward=(0, 0, 1))
    >>> c2 = b.add("C", c, toward=(-1, 0, 0))
    >>> b.add_hydrogens()
    [3, 4, 5, 6, 7, 8, 9]
    >>> b.geometry().symbols
    ['C', 'N', 'C', 'H', 'H', 'H', 'H', 'H', 'H', 'H']


## Builder Methods

Methods for the Builder class


slot_direction(self, key: int, slot: int) -> numpy.ndarray

Get the unit direction of a slot of an atom.

Args:
    key: Atom index.
    slot: Slot index, from 0 to 3.

Returns:
    The direction.

open_slots(self, key: int) -> list[int]

List the empty slots of an atom.

Args:
    key: Atom index.

Returns:
    The empty slots, in order.

add(self, symbol: str, parent: int | None = None, slot: int | None = None, *, toward: numpy._typing._array_like.ArrayLike | None = None, length: float | None = None) -> int

Add an atom.

Args:
    symbol: Atomic symbol.
    parent: Atom to bond to. Must be `None` for the first atom, which
        goes at the origin.
    slot: Slot of `parent` to bond through. If neither this nor
        `toward` is given, use the first empty slot.
    toward: Direction to bond in. The empty slot of `parent` closest
        to this direction is used.
    length: Bond length. Defaults to `xh_length` for bonds to hydrogen
        and `xy_length` otherwise.

Returns:
    Index of the new atom.

Raises:
    ValueError: If the parent, slot, or position is invalid.

add_hydrogens(self, keys: collections.abc.Collection[int] | None = None, *, avoid: numpy._typing._array_like.ArrayLike | None = None) -> list[int]

Fill atoms up to their default valence (see `VALENCES`) with hydrogens.

Args:
    keys: Atoms to fill. Defaults to all heavy atoms.
    avoid: When an atom needs fewer hydrogens than it has empty slots
        (e.g. an amine nitrogen), leave the slots closest to this
        direction empty. By default, the last empty slots are left.

Returns:
    Indices of the new hydrogens.

geometry(self, *, charge: int = 0, spin: int | None = None) -> automol.geom.Geometry

Get the geometry.

Args:
    charge: Charge.
    spin: Number of unpaired electrons. Defaults to the lowest spin
        consistent with the electron count (0 or 1).

Returns:
    The geometry.

umbrella_image(self, key: int, keys: collections.abc.Sequence[int] | None = None, *, geo: automol.geom.Geometry | None = None, normal: numpy._typing._array_like.ArrayLike | None = None) -> tuple[automol.geom.Geometry, list[int]]

Add the mirror image of a branch, e.g. to draw an umbrella inversion.

The branch is reflected through a plane that contains the bond from
`key` to its parent, and that is perpendicular to the empty slot of
`key` (its lone pair). This swaps the sides of the substituents and
the lone pair, as in the inversion of an amine. Both the branch and its
image are kept, so one can be faded afterwards.

Args:
    key: Center of the branch, e.g. an amine nitrogen.
    keys: Atoms to reflect. Defaults to everything bonded beyond `key`,
        away from its parent.
    geo: Geometry to add the image to, e.g. one that already has other
        images. Defaults to `geometry()`. Its first atoms must be the
        builder's.
    normal: Normal of the mirror plane through `key`, overriding the
        default.

Returns:
    The geometry with the image atoms appended, and their indices.

Raises:
    ValueError: If `key` has no parent, or, without `normal`, doesn't
        have exactly one empty slot.


## Functions

Public functions


orient(geo: automol.geom.Geometry, *, port: int = 0) -> scipy.spatial.transform._rotation.Rotation

Rotate a geometry by hand in the browser and get the rotation.

This opens the geometry in py3Dmol in a web browser. Rotate the molecule
with the mouse, then click "Done". The view matches `render`: both look
down the z axis with x to the right and y up.

The rotation is also printed as code, to paste into a drawing script so that
it reproduces the orientation without the viewer.

Args:
    geo: Geometry.
    port: Port for the local server behind the page. The default (0) picks a
        free port.

Returns:
    The rotation, to apply with ``automol.geom.rotate(geo, rot)``.

render(geo: automol.geom.Geometry, out: str | pathlib.Path | None = None, *, config: xyzrender.types.RenderConfig = RenderConfig(canvas_size=800, padding=20.0, atom_scale=3, radius_scale=[], atom_stroke_width=3, atom_stroke_color='black', atom_wash=0.0, atoms_above_bonds=False, bond_width=25, bond_color='#000000', ts_color=None, ts_element=False, ts_dash=(1.2, 2.2), ts_width=1.2, nci_color=None, nci_element=False, nci_dash=(0.08, 2.0), nci_width=1.0, bond_gap=0.6, bond_color_by_element=False, bond_gradient=False, bond_gradient_strength=0.3, bond_outline_color='#000000', bond_outline_width=0.0, gradient=False, atom_gradient_strength=1.0, hue_shift_factor=0.1, light_shift_factor=0.15, saturation_shift_factor=0.15, fog=False, fog_strength=1.2, fog_color=None, hide_bonds=False, unbond=[], bond=[], haptic=False, hide_h=False, show_h_indices=[], auto_hide_h=True, bond_orders=False, ts_bonds=[], nci_bonds=[], vdw_indices=None, vdw_opacity=0.3, vdw_scale=0.8, vdw_gradient_strength=0.5, vdw_interlocking=True, atom_interlocking=False, vdw_interlock_samples=64, vdw_outline_width=0, vdw_outline_color=None, vdw_h_scale=0.7, h_scale=0.6, auto_orient=False, auto_align=True, background='#ffffff', transparent=False, dpi=300, fixed_span=None, fixed_center=None, color_overrides={'C': '#aaaaaa'}, mol_color=None, mo_contours=None, dens_contours=None, esp_surface=None, nci_contours=None, surface_opacity=1.0, flat_mo=False, surface_style='solid', annotations=[], show_indices=False, idx_format='sn', label_font_size=40, label_color='#222222', label_offset=1.5, atom_opacity={}, atom_cmap=None, cmap_range=None, cmap_symm=False, cmap_unlabeled='#ffffff', cmap_palette=None, cbar=False, mo_isovalue=0.05, mo_pos_color='#4682b4', mo_neg_color='#800000', mo_blur_sigma=0.8, mo_upsample_factor=3, mo_outline_width=0.0, mo_outline_color='#000000', dens_isovalue=0.001, dens_color='#4682b4', nci_isovalue=0.3, nci_mode='avg', highlight_groups=[], highlight_colors=['#da70d6', '#3cb371', '#daa520', '#ff7f50', '#9370db', '#ff69b4'], dof=False, dof_strength=3.0, glow_indices=[], glow_strength=5.0, overlay=OverlayConfig(color='#ba55d3', opacity=None, atom_scale=None, atom_stroke_width=None, atom_stroke_color=None, bond_width=None, bond_color=None, bond_outline_width=None, bond_outline_color=None, unbond=[], bond=[], show=[], ts_bonds=[], config=None), ensemble_colors=None, skeletal_style=False, skeletal_label_color=None, cell_data=None, show_cell=True, cell_color='#808080', cell_line_width=10.0, periodic_image_opacity=0.5, axis_colors=('#b22222', '#228b22', '#4169e1'), axis_width_scale=2.0, vectors=[], vector_scale=1.0, vector_color='firebrick', show_convex_hull=False, hull_opacity=0.2, hull_colors=['#4682b4', '#b22222', '#3cb371', '#9370db', '#b8860b', '#5f9ea0'], hull_atom_indices=None, hull_ordered=False, show_hull_edges=True, hull_edge_width_ratio=0.5, pore_spheres=False, pore_sphere_opacity=0.5, pore_sphere_color='#f0d060', pore_node_ids=None, pore_centroids=None, pore_radii=None, style_regions=[], region_specs=None)) -> xyzrender.types.SVGResult

Render a geometry as an SVG, looking down the z axis (x right, y up).

Args:
    geo: Geometry.
    out: Output path. The suffix is replaced with ``.svg``.
    config: xyzrender configuration.

Returns:
    The SVG, which displays inline in Jupyter-like REPLs.

tetrahedral_basis(up: ArrayLike = (0.0, 0.0, 1.0), left: ArrayLike = (-1.0, 0.0, 0.0)) -> numpy.ndarray

Get the four bond directions of a tetrahedral grid.

Direction 0 points along `up`. Direction 1 lies in the plane of `up` and
`left`, on the side of `left`. Directions 2 and 3 follow by rotating
direction 1 about `up` by 120 and 240 degrees (counterclockwise, looking
down from the tip of `up`).

Args:
    up: Direction 0.
    left: Direction in the plane of directions 0 and 1. Only its component
        perpendicular to `up` matters.

Returns:
    Unit vectors, one per row, shape ``(4, 3)``. Each pair makes the
    tetrahedral angle.

Raises:
    ValueError: If `up` is zero or `left` is parallel to `up`.

Example:
    >>> basis = tetrahedral_basis()
    >>> basis.round(6).tolist()[:2]
    [[0.0, 0.0, 1.0], [-0.942809, 0.0, -0.333333]]

orient_page(geo: automol.geom.Geometry) -> str

Make the web page for orienting a geometry in the browser.

Args:
    geo: Geometry.

Returns:
    HTML for a page with a py3Dmol viewer and a "Done" button, which posts
    the view quaternion ``[qx, qy, qz, qw]`` as JSON to ``/done``.

serve_orient_page(geo: automol.geom.Geometry, *, port: int = 0) -> tuple[http.server.ThreadingHTTPServer, list]

Serve the orientation page from a local server, in a background thread.

Args:
    geo: Geometry.
    port: Port to serve on. The default (0) picks a free port.

Returns:
    The server, and a list that receives the view quaternion when the page
    posts it. The server shuts itself down after that.


## Constants

Module-level constants and data


VALENCES

dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
    (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
    d = {}
    for k, v in iterable:
        d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
    in the keyword argument list.  For example:  dict(one=1, two=2)

STYLE

Rendering settings.

TETRAHEDRAL_ANGLE

Convert a string or number to a floating-point number, if possible.

XH_LENGTH

Convert a string or number to a floating-point number, if possible.

XY_LENGTH

Convert a string or number to a floating-point number, if possible.


## Other

Additional exports


tetramol.grid

The tetrahedral grid: ideal bond directions, angles, and lengths.