The Public API and Our Stability Promise

The Public and Stable API

The public and stable Kvantify Qrunch API is loaded as import qrunch as qc. This is the only import you need for most tasks, and the only one that is guaranteed to be supported across versions.

import qrunch as qc

Everything you need for a typical workflow — defining a molecular system, building a quantum-chemical problem, selecting a calculator, and obtaining results — is available through the qc namespace.

Warning

Anything that is not reachable through import qrunch as qc (for example, deeply nested internal modules) is not considered stable, and may change or be removed at any time, without notice, and should not be relied upon.

Backward Compatibility Promise

A script written for an older version of Kvantify Qrunch using the public and stable API is promised to continue to work with newer versions of the code, subject to the deprecation protocol described below.

Note

While such a script is promised to run, we do not guarantee that it produces the same numerical results across versions.

Semantic Versioning

We follow Semantic Versioning (SemVer) for the public and stable API. Given a version number MAJOR.MINOR.PATCH:

  • MAJOR is incremented for incompatible changes to the public and stable API (for example, removing a feature after its deprecation period).

  • MINOR is incremented when functionality is added in a backward-compatible manner (including deprecating — but not yet removing — a feature).

  • PATCH is incremented for backward-compatible bug fixes.

In short, a script written against a given MAJOR version is promised to keep working with any later MINOR or PATCH release of that same MAJOR version, subject to the deprecation protocol described below.

Deprecation Protocol

The backward compatibility promise is subject to our deprecation protocol.

When a feature of the public and stable API is deprecated, we will:

  • issue a deprecation warning when the feature is used, and

  • keep the deprecated feature available for at least one release cycle before it is fully removed.

The deprecation protocol is tied to Semantic Versioning:

  • A feature is deprecated in a MINOR release. This is a backward-compatible change — the feature still works, but now emits a deprecation warning.

  • A deprecated feature is only removed in a subsequent MAJOR release.

This gives you time to migrate your scripts to the recommended replacement before the deprecated feature disappears.

Why Results May Change

As new and improved methods are developed, we reserve the right to change defaults so that the default behavior continues to be a good, balanced trade-off between cost and accuracy. We strive for the default to give an accurate result at a reasonable cost.

Because of this, upgrading to a newer version may cause the default behavior of an existing script to change — typically improving accuracy, cost, or both — even though the script itself is unchanged.

Quick and Accurate Options

To give you explicit control over the trade-off between speed and precision, we further strive to provide easy-to-use options:

  • “quick” options — favor speed over precision.

  • “accurate” options — favor precision over speed.

If you need reproducible behavior that is insulated from changes to the defaults, you must explicit provide all input values and method selection.

See Also