.. _external_interface_v1:

Driver File v1
==============

The top-level entry in the JSON file specifies what action SeQuant should take. At the moment, only code-generation into the ITF format is supported.
Hence, every driver file currently has to start like this:

.. code-block:: json
   {
       "code_generation": {
           "output_format": "itf",
           ...
       }
   }

Beyond :code:`output_format`, the following top-level fields exist:

* :code:`output_path` (required): The path to the file the generated code is written to
* :code:`default_options` (optional): Allows specification of default processing options
* :code:`code_blocks` (required): Specifies a list of code blocks (groups of expressions)

Code Block
----------
Every code block has to have a :code:`name` and a list of :code:`results`. The former is effectively the name of the to-be-generated function that
computes the individual results (expressions), whereas the latter is a list of expressions that shall be computed.

Every result has these mandatory fields:

* :code:`name`: The name of the tensor/scalar variable that shall hold the result of the computed expression
* :code:`equation_file`: Path to the file containing the input expression (cmp :ref:`extint-input`)

Additionally, the following *processing options* may be given. All of them may also be specified as part of the :code:`default_options` block in which
case those values are used, unless explicitly overwritten.

* :code:`density_fitting`: Whether to perform the density-fitting decomposition of the two-electron integral
* :code:`term_by_term`: Whether to split sums into individual summands for processing and code-generation. This yields to more readable but less
  performant code.
* :code:`optimize`: Whether to factorize the equations into a series of binary contractions
* :code:`subexpression_elimination`: Whether to eliminate common subexpressions (only possible when factorizing into binary contractions)
* :code:`expand_symmetrizer`: Whether to explicitly expand (write out) symmetrization operators
* :code:`spintracing`: What kind of spintracing to perform (if any). Possible options are

  * :code:`none`: Don't perform spintracing
  * :code:`closed_shell`: Apply spintracing using an algorithm suitable for closed-shell systems
  * :code:`rigorous`: Apply spintracing using an algorithm that should work for all cases, but is less efficient than :code:`closed_shell`

* :code:`projection`: What kind of projection/transformation to perform with the final result

  * :code:`primitive`: Don't do anything
  * :code:`biorthogonal`: Transform the result into a biorthogonal basis (only applicable to non-scalar results)


Index Space Specification
-------------------------

See :ref:`external_interface_idx_space`. Additionally, the following properties are **required**:

* :code:`name` (String): Name of the index space
* :code:`tag` (String): Tag for this index space (if any). Tags are used to encode the spaces of a tensor's indices in its name. May be empty.

Example
-------

.. code-block:: json

   {
       "code_generation": {
           "output_format": "itf",
           "default_options": {
               "density_fitting": false,
               "term_by_term": false,
               "spintracing": "closed_shell",
               "projection": "biorthogonal"
           },
           "output_path": "something.itfaa",
           "code_blocks": [
               {
                   "name": "First",
                   "results": [
                       {
                           "name": "One",
                           "equation_file": "first.inp",
                           "projection": "primitive"
                       }
                   ]
               },
               {
                   "name": "Second",
                   "results": [
                       {
                           "name": "Two",
                           "equation_file": "second.inp",
                           "projection": "primitive"
                       },
                       {
                           "name": "Three",
                           "equation_file": "third.inp",
                           "spintracing": "rigorous"
                       }
                   ]
               },
           ]
       },
       "index_spaces": [
           {
               "name": "virtual",
               "tag": "e",
               "label": "a",
               "size": 100
           },
           {
               "name": "active",
               "tag": "a",
               "label": "u",
               "size": 5
           },
           {
               "name": "occupied",
               "tag": "c",
               "label": "i",
               "size": 10
           }
       ]
   }