Broombridge Specification v0.2

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Any sidebar with the headings "NOTE," "INFORMATION," or "WARNING" is informative.

Introduction

This section is informative.

Broombridge documents are intended to communicate instances of simulation problems in quantum chemistry for processing using quantum simulation and programming toolchains.

Serialization

This section is normative.

A Broombridge document MUST be serialized as a YAML 1.2 document representing a JSON object as described in RFC 4627 section 2.2. The object serialized to YAML MUST have a property "$schema" whose value is "https://raw.githubusercontent.com/microsoft/Quantum/main/Chemistry/Schema/broombridge-0.2.schema.json", and MUST be valid according to the JSON Schema draft-06 specifications [1, 2].

For the remainder of this specification, "the Broombridge object" will refer to the JSON object deserialized from a Broombridge YAML document.

Unless otherwise explicitly noted, objects MUST NOT have additional properties beyond those specified explicitly in this document.

Additional Definitions

This section is normative.

Quantity Objects

This section is normative.

A quantity object is a JSON object, and MUST have a property units whose value is one of the allowed values listed in Table 1.

A quantity object is a simple quantity object if it has a single property value in addition to its units property. The value of the value property MUST be a number.

A quantity object is a bounded quantity object if it has the properties lower and upper in addition to its units property. The values of the lower and upper properties MUST be numbers. A bounded quantity object MAY have a property value whose value is a number.

A quantity object is a sparse array quantity object if it has the property format and a property values in addition to its units property. The value of format MUST be the string sparse. The value of the values property MUST be an array. Each element of values MUST be an array representing the indices and value of the sparse array quantity.

The indices for each element of a sparse array quantity object MUST be unique across the entire sparse array quantity object. If an index is present with a value of 0, a parser MUST treat the sparse array quantity object identically to a sparse array quantity object in which that index is not present at all.

A quantity object MUST either be

• a simple quantity object,
• a bounded quantity object, or
• a sparse array quantity object.

Examples

This section is informative.

A simple quantity representing $1.9844146837,\mathrm{Ha}$:

coulomb_repulsion:
    value: 1.9844146837
    units: hartree

A bounded quantity representing a uniform distribution over the interval $[-7, -6],\mathrm{Ha}$:

fci_energy:
    upper: -6
    lower: -7
    units: hartree

The following is a sparse array quantity with an element [1, 2] equal to hello and an element [3, 4] equal to world:

sparse_example:
    format: sparse
    units: hartree
    values:
    - [1, 2, "hello"]
    - [3, 4, "world"]

Format Section

This section is normative.

The Broombridge object MUST have a property format whose value is a JSON object with one property called version. The version property MUST have the value "0.2".

Example

This section is informative.

format:                        # required
    version: "0.2"             # must match exactly

Problem Description Section

This section is normative.

The Broombridge object MUST have a property problem_description whose value is a JSON array. Each item in the value of the problem_description property MUST be a JSON object describing one set of integrals, as described in the remainder of this section. In the remainder of this section, the term "problem description object" will refer to an item in the value of the problem_description property of the Broombridge object.

Each problem description object MUST have a property metadata whose value is a JSON object. The value of metadata MAY be the empty JSON object (that is, {}), or MAY contain additional properties defined by the implementor.

Hamiltonian Section

Overview

This section is informative.

The hamiltonian property of each problem description object describes the Hamiltonian for a particular quantum chemistry problem by listing out its one- and two-body terms as sparse arrays of real numbers. The Hamiltonian operators described by each problem description object take the form

$$ H = \sum_{i,j}\sum_{\sigma\in\{\uparrow,\downarrow\}} h_{ij} a^{\dagger}_{i,\sigma} a_{j,\sigma} + \frac{1}{2}\sum_{i,j,k,l}\sum_{\sigma,\rho\in\{\uparrow,\downarrow\}} h_{ijkl} a^\dagger_{i,\sigma} a^\dagger_{k,\rho} a_{l,\rho} a_{j,\sigma}, $$

here $h_{ijkl}= (ij|kl)$ in Mulliken convention.

For clarity, the one-electron term is

$$ h_{ij} = \int {\mathrm d}x \psi^*_i(x) \left(\frac{1}{2}\nabla^2 + \sum_{A}\frac{Z_A}{|x-x_A|} \right) \psi_j(x), $$

and the two-electron term is

$$ h_{ijkl} = \iint {\mathrm d}x^2 \psi^{*}_i(x_1)\psi_j(x_1) \frac{1}{|x_1 -x_2|}\psi_k^{*}(x_2) \psi_l(x_2). $$

As noted in our description of the basis_set property of each element of the integral_sets property, we further explicitly assume that the basis functions used are real-valued. This allows us to use the following symmetries between the terms to compress the representation of the Hamiltonian.

$$ h_{ijkl} = h_{ijlk}=h_{jikl}=h_{jilk}=h_{klij}=h_{klji}=h_{lkij}=h_{lkji}. $$

Note

The term $h_{ijkl}= (ij|kl)$ follows Mulliken index convention, also known as chemists’ notation. The representation used by the .NET and Q# data models follows Dirac or physicists’ notation, where

$$ h_{ijkl} = \iint {\mathrm d}x^2 \psi^{*}_i(x_1)\psi^{*}_j(x_2) \frac{1}{|x_1 -x_2|}\psi_k (x_1) \psi_l(x_2)$$.

Broombridge schema currently only supports Mulliken indexing, such that the deserializer converts between the two conventions when loading data.

Contents

This section is normative.

Each problem description object MUST have a property hamiltonian whose value is a JSON object. The value of the hamiltonian property is known as a Hamiltonian object, and MUST have the properties one_electron_integrals and two_electron_integrals as described in the remainder of this section.

Each problem description object MUST have a property coulomb_repulsion whose value is a simple quantity object. Each problem description object MUST have a property energy_offet whose value is a simple quantity object.

Note

The values of coulomb_repulsion and energy_offet added together capture the identity term of the Hamiltonian.

One-Electron Integrals Object

This section is normative.

The one_electron_integrals property of the Hamiltonian object MUST be a sparse array quantity whose indices are two integers and whose values are numbers. Every term MUST have indices [i, j] where i >= j.

Note

This reflects the symmetry that $h_{ij} = h_{ji}$ which is a consequence of the fact that the Hamiltonian is Hermitian.

Example

This section is informative.

The following sparse array quantity represents the Hamiltonian $$ H = \left(-5.0 (a^{\dagger}_{1,\uparrow} a_{1,\uparrow}+a^{\dagger}_{1,\downarrow} a_{1,\downarrow})+ 0.17 (a^{\dagger}_{2,\uparrow} a_{1,\uparrow}+ a^{\dagger}_{1,\uparrow} a_{2,\uparrow}+a^{\dagger}_{2,\downarrow} a_{1,\downarrow}+ a^{\dagger}_{1,\downarrow} a_{2,\downarrow})\right)\,\mathrm{Ha}. $$

one_electron_integrals:     # required
    units: hartree          # required
    format: sparse          # required
    values:                 # required
        # i j f(i,j)
        - [1, 1, -5.0]
        - [2, 1,  0.17]

Note

Broombridge uses 1-based indexing.

Two-Electron Integrals Object

This section is normative.

The two_electron_integrals property of the Hamiltonian object MUST be a sparse array quantity with one additional property called index_convention. Each element of the value of two_electron_integrals MUST have four indices.

Each two_electron_integrals property MUST have a index_convention property. The value of the index_convention property MUST be one of the allowed values listed in Table 1. If the value of index_convention is mulliken, then for each element of the two_electron_integrals sparse array quantity, a parser loading a Broombridge document MUST instantiate a Hamiltonian term equal to the two-electron operator $h_{i, j, k, l} a^\dagger_i a^\dagger_j a_k a_l$, where $i$, $j$, $k$, and $l$ MUST be integers of value at least 1, and where $h_{i, j, k, l}$ is the element [i, j, k, l, h(i, j, k, l)] of the sparse array quantity.

Symmetries

This section is normative.

If the index_convention property of a two_electron_integrals object is equal to mulliken, then if an element with indices [i, j, k, l] is present, the following indices MUST NOT be present unless they are equal to [i, j, k, l]:

• [i, j, l, k]
• [j, i, k, l]
• [j, i, l, k]
• [k, l, i, j]
• [k, l, j, i]
• [l, k, j, i]

Note

Because the two_electron_integrals property is a sparse array quantity object, no indices may be repeated on different elements. In particular, if an element with indices [i, j, k, l] is present, no other element may have those indices.

Example

This section is informative.

The following object specifies the Hamiltonian

$$ H = \frac12 \sum_{\sigma,\rho\in\{\uparrow,\downarrow\}}\Biggr( 1.6 a^{\dagger}_{1,\sigma} a^{\dagger}_{1,\rho} a_{1,\rho} a_{1,\sigma}- 0.1 a^{\dagger}_{6,\sigma} a^{\dagger}_{1,\rho} a_{3,\rho} a_{2,\sigma}- 0.1 a^{\dagger}_{6,\sigma} a^{\dagger}_{1,\rho} a_{2,\rho} a_{3,\sigma}- 0.1 a^{\dagger}_{1,\sigma} a^{\dagger}_{6,\rho} a_{3,\rho} a_{2,\sigma}- 0.1 a^{\dagger}_{1,\sigma} a^{\dagger}_{6,\rho} a_{2,\rho} a_{3,\sigma} $$ $$- 0.1 a^{\dagger}_{3,\sigma} a^{\dagger}_{2,\rho} a_{6,\rho} a_{1,\sigma}- 0.1 a^{\dagger}_{3,\sigma} a^{\dagger}_{2,\rho} a_{1,\rho} a_{6,\sigma}- 0.1 a^{\dagger}_{2,\sigma} a^{\dagger}_{3,\rho} a_{6,\rho} a_{1,\sigma}- 0.1 a^{\dagger}_{2,\sigma} a^{\dagger}_{3,\rho} a_{1,\rho} a_{6,\sigma}\Biggr)\,\textrm{Ha}. $$

two_electron_integrals:
    index_convention: mulliken
    units: hartree
    format: sparse
    values:
        - [1, 1, 1, 1,  1.6]
        - [6, 1, 3, 2, -0.1]

Initial State Section

This section is normative.

The initial_state_suggestion object whose value is a JSON array specifies initial quantum states of interest to the specified Hamiltonian. Each item in the value of the initial_state_suggestion property MUST be a JSON object describing one quantum state, as described in the remainder of this section. In the remainder of this section, the term "state object" will refer to an item in the value of the initial_state_suggestion property of the Broombridge object.

State object

This section is normative.

Each state object MUST have a label property containing a string. Each state object MUST have a method property. The value of the method property MUST be one of the allowed values listed in Table 3. Each state object MAY have a property energy whose value MUST be a simple quantity object.

If the value of the method property is sparse_multi_configurational, the state object MUST have a superposition property containing an array of basis states and their unnormalized amplitudes.

For example, the initial states $$ \ket{G0}=\ket{G1}=\ket{G2}=(a^{\dagger}_{1,\uparrow}a^{\dagger}_{2,\uparrow}a^{\dagger}_{2,\downarrow})\ket{0} $$ $$ \ket{E}=\frac{0.1 (a^{\dagger}_{1,\uparrow}a^{\dagger}_{2,\uparrow}a^{\dagger}_{2,\downarrow})+0.2 (a^{\dagger}_{1,\uparrow}a^{\dagger}_{3,\uparrow}a^{\dagger}_{2,\downarrow})}{\sqrt{|0.1|^2+|0.2|^2}}\ket{0}, $$ where $\ket{E}$ has energy $0.987 \textrm{Ha}$, are represented by

initial_state_suggestions: # optional. If not provided, spin-orbitals will be filled to minimize one-body diagonal term energies.
  - label: "|G0>"
    method: sparse_multi_configurational
    superposition:
      - [1.0, "(1a)+","(2a)+","(2b)+","|vacuum>"]
  - label: "|G1>"
    method: sparse_multi_configurational
    superposition:
      - [-1.0, "(2a)+","(1a)+","(2b)+","|vacuum>"]
  - label: "|G2>"
    method: sparse_multi_configurational
    superposition:
      - [1.0, "(3a)","(1a)+","(2a)+","(3a)+","(2b)+","|vacuum>"]
  - label: "|E>"
    energy: {units: hartree, value: 0.987}
    method: sparse_multi_configurational
    superposition:
      - [0.1, "(1a)+","(2a)+","(2b)+","|vacuum>"]
      - [0.2, "(1a)+","(3a)+","(2b)+","|vacuum>"]

If the value of the method property is unitary_coupled_cluster, the state object MUST have a cluster_operator property whose value is a JSON object. The JSON object MUST have a reference_state property whose value is a basis state. The JSON object MAY have a one_body_amplitudes property whose value is an array of one-body cluster operators and their amplitudes. The JSON object MAY have a two_body_amplitudes property whose value is an array of two-body cluster operators and their amplitudes. containing an array of basis states and their unnormalized amplitudes.

For example, the state $$ \ket{\text{reference}}=(a^{\dagger}_{1,\uparrow}a^{\dagger}_{2,\uparrow}a^{\dagger}_{2,\downarrow})\ket{0}, $$

$$ \ket{\text{UCCSD}}=e^{T-T^\dagger}\ket{\text{reference}}, $$

$$ T = 0.1 a^{\dagger}_{3,\uparrow}a_{2,\downarrow} + 0.2 a^{\dagger}_{2,\uparrow}a_{2,\downarrow} - 0.3 a^{\dagger}_{1,\uparrow}a^{\dagger}_{3,\downarrow}a_{3,\uparrow}a_{2,\downarrow} $$ is represented by

initial_state_suggestions: # optional. If not provided, spin-orbitals will be filled to minimize one-body diagonal term energies.
  - label: "UCCSD"
    method: unitary_coupled_cluster
    cluster_operator: # Initial state that cluster operator is applied to.
        reference_state: 
          [1.0, "(1a)+", "(2a)+", "(2b)+", '|vacuum>']
        one_body_amplitudes: # A one-body cluster term is t^{q}_{p} a^\dag_p a_q   
            - [0.1, "(3a)+", "(2b)"]
            - [-0.2, "(2a)+", "(2b)"]
        two_body_amplitudes: # A two-body unitary cluster term is t^{rs}_{pq} a^\dag_p a^\dag_q a_r a_s
            - [-0.3, "(1a)+", "(3b)+", "(3a)", "(2b)"]

Basis Set Object

This section is normative.

Each problem description object MAY have a basis_set property. If present, the value of the basis_set property MUST be an object with two properties, type and name.

The basis functions identified by the value of the basis_set property MUST be real-valued.

Note

The assumption that all basis functions are real-valued may be relaxed in future versions of this specification.

Tables and Lists

Table 1. Allowed Physical Units

This section is normative.

Any string specifying a unit MUST be one of the following:

• hartree
• ev

Parsers and producers MUST treat the following simple quantity objects as equivalent:

- {"units": "hartree", "value": 1}
- {"units": "ev", "value": 27.2113831301723}

Table 2. Allowed Index Conventions

This section is normative.

Any string specifying an index convention MUST be one of the following:

• mulliken

This section is informative.

Additional index conventions may be introduced in future versions of this specification.

Interpretation of Index Conventions

This section is informative.

Table 3. Allowed State methods

This section is normative.

Any string specifying a state method MUST be one of the following:

• sparse_multi_configurational
• unitary_coupled_cluster

This section is informative.

Additional state methods may be introduced in future versions of this specification.