# Quickstart: your first calculation

This chapter gets you from a blank Python prompt to a real quantum-chemistry result in a few lines. We
will compute the energy of a **water molecule**, switch the method to DFT, and read out an atomic-charge
property — enough to see the whole shape of a qc-rs calculation.

:::{note} Before you start
You need qc-rs installed and importable (`import qc` works). If not, do
[Installation & the build](installation-and-make-setup.md) first.
:::

## Run your first calculation

Type this into a Python session (or a script, or a Jupyter notebook cell):

```python
import qc

# 1. Build a checkpoint: water, in the cc-pVDZ basis, coordinates in ångström.
mychk = qc.chk.new(
    atom="O 0.0000 0.0000 0.1173; H 0.0000 0.7572 -0.4692; H 0.0000 -0.7572 -0.4692",
    ao="cc-pvdz",
    unit="angstrom",
)

# 2. Add a restricted Hartree–Fock (RHF) step, and run it.
mychk = mychk.scf(ref="r").run()

# 3. Read the result.
print(f"energy    = {mychk.scf.energy:.6f} hartree")
print(f"converged = {mychk.scf.converged}")
```

You should see:

```text
energy    = -76.026772 hartree
converged = True
```

That is a complete Hartree–Fock calculation. Congratulations — you just solved the electronic Schrödinger
equation (approximately!) for water.

## What just happened?

Three ideas, one per line:

1. **`qc.chk.new(...)` builds a *checkpoint*** — the object that holds your molecule and, later, all
   results. Here we gave it the geometry (`atom=`), the basis set (`ao="cc-pvdz"`), and the unit of the
   coordinates (`unit="angstrom"`).
2. **`.scf(ref="r")` adds a step** — a self-consistent-field calculation. `ref="r"` means *restricted*
   (closed-shell) Hartree–Fock. Adding a step does **no** heavy computation yet; it just records what you
   want.
3. **`.run()` does the work**, and afterwards **`mychk.scf.energy`** reads the result back out.

This build-then-run pattern is the heart of qc-rs. We look at it properly in
[Core concepts](concepts.md).

:::{tip} Watch it run: `run(log=...)`
By default `.run()` is **silent** — it just computes. Pass **`run(log="stdout")`** to stream a live,
quantum-chemistry-style transcript instead: the system summary, the SCF cycle-by-cycle energy table, and the
convergence check. A few options you will reach for early — `log_style="modern"`/`"orca"` picks the visual
style, and `plot=True` draws the SCF convergence curve inline (in a notebook with `%matplotlib inline`).
After a run, `mychk.log()` replays the transcript without recomputing. The full set is shown in
[Editor setup](editor-vscode.md) and the [Logging & output chapter](../20-guide/logging-output.md).
:::

:::{tip} Make it faster: `nthread=`
By default a calculation uses a **single CPU core**. Pass **`run(nthread=8)`** to spread the work across 8
cores of your machine — shared-memory **thread** parallelism that speeds up almost every run on a laptop or
a single node, with no extra setup. (Running across *many machines* with **MPI process** parallelism,
`nmpi=`, is more advanced — we introduce it later in
[Parallel computing & HPC](../30-hpc/index.md). For now, `nthread=` is all you need.)
:::

The result carries much more than the energy. For instance `mychk.scf.ncycle` is how many SCF iterations it
took to converge, and `mychk.scf.energy_components` breaks the total energy into its physical pieces
(kinetic, nuclear attraction, Coulomb, exchange, …). You will meet these as you need them.

:::{tip} A Python note
`f"...{mychk.scf.energy:.6f}..."` is an **f-string** — Python substitutes the value of the expression in
`{...}` into the text, and `:.6f` formats it with six digits after the decimal point.
:::

## Switch to DFT

Want density-functional theory instead of Hartree–Fock? Change **one thing** — add a functional with
`xc=`:

```python
mydft = qc.chk.new(
    atom="O 0.0000 0.0000 0.1173; H 0.0000 0.7572 -0.4692; H 0.0000 -0.7572 -0.4692",
    ao="cc-pvdz", unit="angstrom",
).scf(ref="r", xc="b3lyp").run()

print(f"{mydft.scf.energy:.6f} hartree")   # -76.420369
```

The B3LYP energy (`-76.420369`) is lower than the Hartree–Fock one because it includes electron
*correlation* — a concept we develop in [Foundations](../10-foundations/dft-kohn-sham.md).

## Your first property

An energy is only the beginning. From the same converged calculation you can ask for hundreds of
properties. Here are the **Mulliken atomic charges**:

```python
q = qc.prop.chrg.mulliken(mychk)
print(q["charges"])       # [-0.3060, 0.1530, 0.1530]
print(q["atom_labels"])   # ['O', 'H', 'H']
```

Oxygen carries a partial **negative** charge and each hydrogen a partial **positive** charge — exactly the
polarity you expect for water. The whole property suite lives in
[Molecular properties](../20-guide/properties/index.md).

## Open-shell molecules (radicals)

Not every molecule is a closed shell. For a radical — an odd number of electrons, or unpaired spins — use
**unrestricted** Hartree–Fock (`ref="u"`) and set the spin. Here is the methyl radical (CH₃•), a doublet:

```python
ch3 = qc.chk.new(
    atom="C 0 0 0; H 0 1.079 0; H 0.934 -0.539 0; H -0.934 -0.539 0",
    ao="cc-pvdz", unit="angstrom",
    spin=2,                       # spin multiplicity 2S+1: 2 = doublet (one unpaired electron)
).scf(ref="u").run()              # ref="u" = unrestricted

print(f"{ch3.scf.energy:.6f} hartree")     # -39.563802
print(qc.prop.spin.s_squared(ch3))         # 0.7612   (ideal doublet: 0.75)
```

:::{tip} A note on spin
`spin` is the **multiplicity** `2S+1`: `1` = singlet (all electrons paired), `2` = doublet (one unpaired),
`3` = triplet (two unpaired). Use `ref="r"` for closed shells, `ref="u"` (unrestricted) or `ref="ro"`
(restricted-open) for open shells.
:::

The `⟨S²⟩ ≈ 0.76` here is close to the ideal `0.75` of a pure doublet; small excesses measure a little
*spin contamination*, which the [SCF chapter](../20-guide/scf.md) explains.

## Where to next

- To relax a structure and then analyze it, work through the
  [Tutorial: DFT geometry optimization → properties](tutorial-dft-to-properties.md).
- To understand *why* the checkpoint/step/run pattern is shaped this way, read
  [Core concepts](concepts.md).
- To understand *what* Hartree–Fock and DFT actually compute, read [Foundations](../10-foundations/index.md).