List the stability job type in the input YAML reference

input_reference.rst had no mention of `stability` at all, and its job_types example
listed six keys out of twelve, so the only place the feature was documented was
advanced.rst -- which describes behaviour and is not where a user goes to find out
which keys an input file accepts. The feature was therefore discoverable only by
reading the settings module.

`stability` is added to the job type key list and to the example with its default,
and the example now states which keys default to true and which to false, since the
example itself lists a mixture of the two and previously implied that the ones it
omitted were unavailable rather than defaulted.

A short section states what the analysis is, that ARC has implemented it for Gaussian
so far and that other ESSs are not wired up yet, when it runs (once per species, after
that species' freq job, for a TS or for a species whose freq job actually ran
restricted, at a DFT or HF level, with the freq job's checkfile), and what the user
gets back. Which instabilities invalidate analytic frequencies, and what an adopted
verdict does and does not correct, stay in advanced.rst; this section links there
rather than restating them.

The `specific_job_type` interaction is documented because it is a trap. That key
replaces job_types wholesale with a dictionary in which only the named type is true,
so `specific_job_type: stability` is accepted -- stability is a key of
default_job_types, so no InputError is raised -- and then produces nothing at all,
because opt, freq and sp are all false and run_stability_job is only ever reached from
post_freq_actions. bde is special-cased to re-enable opt/fine/freq/sp; stability is
not. Verified against initialize_job_types rather than inferred: specific_job_type
'stability' yields opt False, freq False, sp False, stability True. The reference now
says to request it through job_types and says why.

Deliberately not documented here: which other programs implement a stability analysis
and under what keyword. ORCA and Q-Chem both do, but their exact syntax was not
verified against their manuals for this commit, and an unverified keyword in ARC's
documentation is worse than none. The text is kept to what ARC does.

Also records that the job type now runs in ORCA as well as in Gaussian, that ORCA always
follows an instability it finds, and that the two codes test the same space and agree on
the verdict, with the sector of a restricted reference's instability read off the solution
ORCA relaxes into.

Author: calvinp0

docs/source/input_reference.rst

@@ -223,6 +223,7 @@ Current job type keys are:
 * ``rotors``
 * ``irc``
 * ``orbitals``
+* ``stability``
 * ``onedmin``
 * ``bde``
 
@@ -242,6 +243,44 @@ Example:
      freq: true
      sp: true
      rotors: false
+     stability: false
+
+``conf_opt``, ``opt``, ``fine``, ``freq``, ``sp``, ``rotors`` and ``irc`` default to
+``true`` when omitted; ``conf_sp``, ``orbitals``, ``stability``, ``onedmin`` and ``bde``
+default to ``false``.
+
+Wavefunction Stability Analysis
+-------------------------------
+
+``stability`` is off by default and is opt-in through ``job_types``. ARC has implemented
+the analysis for Gaussian and for ORCA so far; other ESSs are not wired up yet, and a run
+whose frequency jobs go to another ESS is told so once per ESS in the log rather than
+silently producing nothing. The two ESSs test the same space and agree on the verdict; in
+ORCA the analysis always follows an instability it finds, since ORCA 6.0.0 aborts rather
+than merely reporting one, and the sector of a restricted reference's instability is read
+off the solution it relaxes into.
+
+It runs once per species, after that species' frequency job, and only for a transition
+state or for a species whose frequency job actually ran with a restricted reference - a
+restricted reference is the only one the analysis can inform, since a restricted solution
+gives the same energy as an unrestricted one if and only if it is stable. It is further
+limited to DFT and Hartree-Fock frequency levels, and needs the checkfile the frequency
+job used, so that the SCF under test is the one the Hessian was built from.
+
+What it buys you: a verdict recorded in the log and in ``output.yml`` saying whether the
+converged wavefunction is a genuine minimum in the space of orbital rotations, together
+with the label and eigenvalue of any negative stability-matrix root, and whether the
+analytic frequencies are invalidated by it. For a transition state the verdict can also
+decide the restricted-versus-unrestricted reference of the jobs that follow. See
+:ref:`Advanced Features <advanced>` for the full treatment, including which instabilities
+invalidate analytic frequencies and what an adopted verdict does and does not correct.
+
+``specific_job_type`` cannot be used to request it. That key replaces ``job_types``
+wholesale with a dictionary in which only the named job type is ``true``, so
+``specific_job_type: stability`` switches off the ``opt``, ``freq`` and ``sp`` jobs the
+analysis is spawned from and nothing runs at all (``bde`` is special-cased to re-enable
+them; ``stability`` is not). Any other value of ``specific_job_type`` likewise sets
+``stability`` to ``false``. Request it through ``job_types``.
 
 ESS Settings
 ------------