Sessions: lineages, seeds and commits¶
A session evaluates one molecule at many geometries: the steps of an optimization, the
branches of an IRC, the displaced points of a finite-difference Hessian. Open one with
qccompute.session(inp) (or runner.session(inp)); the input pins the program, model,
keywords, atoms, charge and multiplicity, and its geometry and calctype are the defaults
of a request.
Who gains from a session¶
Only a program with sessions of its own (capabilities().sessions, like the toy program
here) keeps anything between requests: orbitals for a warm start, a
pinned grid. Its frames say record["warm_start"]: true when a request continued a
history. Any other program (most external programs, tblite, a FunctionProgram) gets a
session over compute: every request is computed from scratch and its frames say
warm_start: false. Such a session is a convenience (one object, the same methods for
every program), not a speed-up.
from qccompute.program import capabilities_of, find_program
capabilities_of(find_program("tblite")).sessions # False: no warm starts
Lineages, seeds and commits¶
- Lineage: any JSON value naming one history (
"ts",["irc", "forward"]);Noneis the default. A request continues its lineage's last committed success. - Seed: lineages to start from when the request's own lineage has no history yet, in order: both IRC branches start from the transition state's history.
- Commit:
True(the default) makes a success the lineage's new history;Falsereads the history without moving it (displaced points of a finite difference, a trial step). - Reset:
s.reset(lineage)forgets one lineage's history (after a large jump),s.reset()all of them.
A failed request raises qcdata.ProgramError; the lineage's history is untouched and
the session stays usable, so a caller may retry a smaller step. compute_many runs every
request (requests of one lineage in order, different lineages possibly side by side),
then raises qcdata.ProgramErrors if any failed, with every frame in results.
"""A session: one molecule at many geometries, with lineages, seeds and commits.
The toy program (Lennard-Jones argon, with sessions of its own) stands in for any
program that warm-starts. Its frames say whether they were warm-started and, in its own
record, which lineage's history they continued (``from_lineage``).
"""
import numpy as np
from qcdata import CalcType, Model, ProgramInput, Request, Structure
import qccompute
from qccompute.program import capabilities_of, find_program
from qccompute.testing import toy
qccompute.register_program(toy.program)
argon = Structure(
symbols=["Ar", "Ar", "Ar"],
geometry=np.array([[0.0, 0.0, 0.0], [7.2, 0.0, 0.0], [3.0, 6.1, 0.4]]), # bohr
)
inp = ProgramInput(
program="toy", calctype=CalcType.gradient, structure=argon, model=Model(method="lj")
)
x = np.asarray(argon.geometry)
# Only a program with sessions of its own warm-starts; any other program's session
# computes every request from scratch (warm_start is always False).
program = find_program("toy")
assert program is not None
print("warm-starts:", capabilities_of(program).sessions)
with qccompute.session(inp) as s:
first = s.compute() # the input's own geometry: nothing to continue from yet
second = s.compute(x * 1.01) # continues the default lineage's last success
print(first.record["warm_start"], second.record["warm_start"]) # False True
# A lineage is any JSON value naming one history. Optimize towards a transition
# state in lineage "ts", then start both IRC branches from it: `seed` names the
# lineage to start from when the request's own lineage has no history yet.
s.compute(x * 1.005, lineage="ts")
forward = s.compute(x * 1.02, lineage=["irc", "forward"], seed=["ts"])
backward = s.compute(x * 0.99, lineage=["irc", "backward"], seed=["ts"])
print(forward.record["from_lineage"], backward.record["from_lineage"]) # ts ts
later = s.compute(x * 1.03, lineage=["irc", "forward"]) # now its own history
print(later.record["from_lineage"]) # ['irc', 'forward']
# Finite differences around the TS: each displaced point starts from the TS's
# history but, with commit=False, leaves it as it was for the next real step.
step = 1e-3
displaced = [
Request(
positions=x * 1.005 + sign * step * e.reshape(3, 3),
lineage="ts",
commit=False,
)
for e in np.eye(9)
for sign in (1, -1)
]
energies = np.array([f.results.energy for f in s.compute_many(displaced)])
gradient = (energies[0::2] - energies[1::2]) / (2 * step)
print(np.round(gradient.reshape(3, 3), 6))
s.reset("ts") # forget one lineage's history (after a large jump); reset(): all