External Interface

The external interface is supposed to allow interfacing with SeQuant from the outside, without having to write a C++ program that links to the SeQuant library. The idea is to specify equations in text form and then submit them to SeQuant for processing. This works by using a JSON driver file that contains instructions for what you want SeQuant to do.

Input Format

See Serialization for the format in which the input equations are expected to be.

Note

It is assumed that the input always specifies a result. That is, it is of the format lhs = rhs. Furthermore, every input file may only contain a single result.

Running the Tool

The external interface is built as the external_interface executable and is invoked as

external_interface --driver <path-to-driver.json> [--verbose]

--driver (required) is the path to the JSON driver file to execute. --verbose raises the log level to include debug output; without it, only a short progress line per processing step plus any errors are printed.

Before doing anything else, the tool changes its working directory to the driver file’s own directory. This is why all paths specified within the driver file are resolved relative to the driver file’s location rather than to the shell’s working directory (see the note below).

The driver JSON file may contain // and /* */ comments, which are stripped before parsing - a small but handy authoring convenience that plain JSON doesn’t otherwise allow.

Any error encountered anywhere - be it a malformed driver file, an invalid option, or a failure while processing a step - aborts the run immediately (reported on stderr, non-zero exit code). There is no partial or best-effort processing.

Driver File

There currently are two mostly independent implementations of the external interface available. Which version you want to use is determined by the driver_format_version key in the JSON driver. If you set it to a value of 1, you will get the old/legacy version of the interface. The rest of the JSON file is expected to follow the syntax described in Driver File v1. If you set it to 2, you will be using the new, modular external interface. Its driver syntax is described in Driver File v2. If the field is unset, the code defaults to 1 for reasons of backwards compatibility.

The main difference between the two versions is that the newer version is much more modular and flexible. Therefore, it is recommended that you use that for all new tasks.

Note

All paths specified in the driver file are understood to be relative to the JSON file’s location (unless absolute paths are used, of course).

Common Syntax

Index Space Specification

Every driver file has to contain the definition of index spaces that are used in expressions. It lives under the top-level key index_spaces and is expected to be an array of objects. These objects can have the following properties

  • label (required, String): Label used in expressions for indices in this space, e.g. in i1 the label is i.

  • size (required, Integer): The (approximate) size/dimension of indices in this index space. This affects things like factorization into binary contractions.

  • real_valued (Boolean): Whether the field used in this index space is real- rather than complex-valued. This affects for instance tensors with hermitian braket symmetry.