A few notes for Python beginners

A few notes for Python beginners#

This manual is not a Python tutorial, but a handful of Python features come up constantly when driving qc-rs. This appendix collects the “Python note” callouts scattered through the chapters into one reference. If you know Python, skip it.

Keyword arguments#

qc-rs calls label each value by name:

qc.chk.new(atom="H 0 0 0; F 0 0 0.9", ao="cc-pvdz", unit="angstrom", charge=0, spin=1)

atom=, ao=, … are keyword arguments: the order does not matter, and the call documents itself. You will see this style everywhere in qc-rs. A * in a signature (e.g. scf(mychk, *, ref="r", …)) means the arguments after it are keyword-only — you must name them.

f-strings#

An f-string substitutes an expression into text; :.6f formats a float with six decimals:

print(f"energy = {mychk.scf.energy:.6f} hartree")   # energy = -76.026772 hartree

Triple-quoted strings#

"""… """ is a multi-line string — the natural way to write a geometry, one atom per line:

atom = """
    O   0.000   0.000   0.117
    H   0.000   0.757  -0.469
    H   0.000  -0.757  -0.469
"""

Leading/trailing blank lines and indentation are fine; qc-rs ignores them.

Lists vs dicts#

  • A list [...] is an ordered sequence: ao=["cc-pvtz", "cc-pvdz"] is not how you set per-atom bases.

  • A dict {key: value} maps names to values: ao={"O": "cc-pvtz", "H": "cc-pvdz"} gives each element its own basis. Many qc-rs options (ao=, pcm=, iop=) accept a dict.

Method chaining#

Each workflow verb returns a new checkpoint, so you can chain them left to right:

mychk = qc.chk.new(atom=..., ao="cc-pvdz").scf(ref="r").run()

reads as “make a checkpoint → add an SCF step → run it.” The functional form qc.scf(qc.chk.new(...), ref="r").run() is identical but reads inside-out.

Reading arrays (numpy)#

Some accessors return NumPy arrays. np.asarray(...) makes sure you have one, .shape gives its dimensions, and np.round(...) tidies the display:

import numpy as np
g = np.asarray(mychk.scf.gradient)   # shape (natom, 3)
print(g.shape, np.round(g, 4))

Virtual environments and uv#

A virtual environment (venv) is an isolated Python with its own packages, so projects don’t clash. qc-rs uses uv to manage one. Two things to remember:

  • Your notebook/editor kernel must be the venv that has qc-rs installed, or import qc fails (editor chapter). Check with import sys; print(sys.executable).

  • uv add <pkg> prunes the editable qc-rs extension — rebuild it afterwards (make install).

Notebooks: %matplotlib inline#

In a Jupyter notebook, this “magic” makes plots appear in the cell:

%matplotlib inline
mychk.plot_convergence()

Set the magic in a cell — do not pip install inside a cell (install packages in the environment with uv).

importlib for basis data#

The bundled basis files are ordinary Python modules; load one with importlib:

import importlib
cc_pvdz = importlib.import_module("qc.basis.cc_pvdz")
cc_pvdz.O.description    # "cc-pvdz:O"

That is the whole of the Python you need to follow this manual — everything else is qc-rs and chemistry.