Handling input/output data

There are two ways to handle input and output data to perform quantum chemistry calculations with Qamuy:

• YAML/JSON data: These are simple text files that contain input and output data. It is used when you run a calculation with the qamuy command.

• Python objects: In a Python program, you can handle input and output data as objects. It is useful for generating a lot of input data or for using Qamuy in Jupyter Notebook.

YAML/JSON data

Both YAML and JSON are text formats that can describe structural data in a concise manner. Qamuy supports the YAML and JSON formats for input and output data. These two formats are equivalent, so you can choose either of them according to your preference.

Example of input data (YAML)

ansatz:
  type: SYMMETRY_PRESERVING
  depth: 5
optimizer:
  type: BFGS
target_molecule:
  geometry:
    atoms: [H, H]
    coordinates:
      - - [0.0, 0.0, -0.35]
        - [0.0, 0.0, 0.35]
  basis: sto-3g
  multiplicity: 1

Example of input data (JSON)

{
  "ansatz": {
    "type": "SYMMETRY_PRESERVING",
    "depth": 5
  },
  "optimizer": {
    "type": "BFGS"
  },
  "target_molecule": {
    "geometry": {
      "atoms": ["H", "H"],
      "coordinates": [
        [
          [0.0, 0.0, -0.35],
          [0.0, 0.0, 0.35]
        ]
      ]
    },
    "basis": "sto-3g",
    "multiplicity": 1
  }
}

Use qamuy run command to run a calculation based on a YAML/JSON format input file. The following command executes the calculation specified in the input file on the cloud.

In the case of a JSON file (input.json):

$ qamuy run input.json

In the case of a YAML file (input.yaml):

$ qamuy run input.yaml

The result is shown in the standard output by default. You can save the result to a file with the -o option. You can specify the saving format with the -f option (if not specified, the result is saved in JSON).

In case of saving in JSON format:

$ qamuy run input.json -o output.json

If you want to save in YAML format:

$ qamuy run input.yaml -f yaml -o output.yaml

Complex numbers

In the input and output data of the YAML/JSON format, complex numbers are represented as an object (mapping), containing two real numbersreal and imag.

YAML format:

value:
  real: 1.0
  imag: 2.0

JSON format:

{
  "real": 1.0,
  "imag": 2.0
}

Enumerated types

There are some attributes in input/output data whose value is selected from a set of choices (enumerated type). In YAML/JSON format input/output data, such a value is represented as a string. If a string is specified that is not in the selection, an error is returned.

In the following example, the type in the optimizer is selected from a set of choices (BFGS, NFT, …).

YAML format:

optimizer:
  type: BFGS

JSON format:

{
  "optimizer": {
    "type": "BFGS"
  }
}

Input and output data as Python objects

With Qamuy Client SDK, you can create input data, perform calculations, and analyze output data within a Python program. In this case, you will be dealing with input and output data as Python objects through functions in the Python SDK.

Input data objects are created using the classes and functions in the qamuy.chemistry package. Each object has attributes with names corresponding to their description in YAML/JSON format, whose values can be referenced and assigned.

import qamuy.chemistry as qy

input = qy.QamuyChemistryInput()
input.target_molecule.basis = "sto-3g"
print(input.target_molecule.basis) # => sto-3g

After creating the input data object, run the calculation on the cloud using the qamuy.client.Client class.

from qamuy.client import Client

client = Client()
job = client.submit(input)
results = client.wait_and_get_job_results([job])
result = results[0]

The output data objects also have attributes with names corresponding to description in YAML/JSON format, allowing you to reference and analyze the calculation results.

quantum_result = result.molecule_result.quantum_device_result
print(list(quantum_result.vqe_log.opt_params)) # => [-0.10486732118823552]

See Input and output data for more information on input and output data, and Using Qamuy programatically on using the Python SDK to create input data, execute calculations, and analyze output data.

Complex numbers

Within the Python SDK’s input and output objects, complex numbers are treated as values of Python’s complex type.

print(transition_dipole_moment.value[0]) # => (-0.8089680491698781+0j)

Enumerated types

There are some attributes in input/output data whose value is selected from a set of choices (enumerated type). Within the Python SDK’s input and output objects, such values can be handled as Enum (more precisely, IntEnum). When assigning such a value to an input/output object, it is possible to use a string that represents the name of the value as well as the Enum value. If a string that is not in the selection is specified, an error is reported.

The following example shows several ways to specify the type in the optimizer.

import qamuy.chemistry as qy

optimizer = qy.Optimizer(type="BFGS")
optimizer.type # => <Type.BFGS: 1>
# Assigning an Enum value
optimizer.type = qy.Optimizer.Type.NFT
optimizer.type # => <Type.NFT: 3>
# Assigning a string value
optimizer.type = "POWELL"
optimizer.type # => <Type.POWELL: 5>
# Assigning a string of a non-existent value returns an error
optimizer.type = "INVALID" # => ValueError: unknown enum label "INVALID"