.. _examples:

Example Applications
====================

In the current software revision of REDAC, users are supposed to be given
circuit configuration files (a concept also known as
`netlist <https://en.wikipedia.org/wiki/Netlist>`_) which are refered to as
``config.json`` in the following. These circuit configuration
files encode the actual mathematical problems. Their generation is done by
software by tooling which will provided at a later stage.

The usage of REDAC is currently therefore basically the submission of a
``config.json`` file, next to some basic information about the simulation
parameters (such as simulation runtimes or for data querying of measurement
variables).

Given the Python client (section :ref:`first_steps`), you can invoke
examples either from your operating system command line or from python code,
using the given client as a library.

For the following example, please download the :download:`exemplaric config.json file <config.json>`
first.

.. only:: latex

  In the print version of this document, a compact version of the config
  file is printed for illustrative purpose. Please do not try to type in
  this file at your computer but instead head to the online version of
  this document and download the ASCII file for straight usage.
      
  .. literalinclude:: compact-config.json
     :language: json
     :linenos:

We primarily support the Python programming language as the reference
implementation. The way how to upload a configuration file is like

::

  you@localhost> redacli run --host https://redac.anabrid.com [--partition partition_id] config.json
  [CSV output of measurement variables]

or, straight from the python programming language (REPL):

::

  you@localhost> python
  >>> import json
  >>> from anabrid.redaccess.api.client.redac_client import REDACClient
  >>> redac = REDACClient("https://redac.anabrid.com")
  >>> redac.login(username, password) # to be set by the user
  >>> with open("config.json", "r") as f:
  >>>     config = json.load(f)
  >>> job_id, results = redac.solve(config, 0) 
  >>> logs = redac.log(job_id)

Afterwards, the variables `results` resp. `logs` will hold the job results
in a JSON format and the job's log as a string array.

Note that other than these high-level functions, `REDACClient` contains several
functions that allow to submit one or multiple job asynchronously, to multiple
partitions, then wait for them to finish and collect their results all at once:

::

  import asyncio
  import json
  from anabrid.redaccess.api.client.redac_client import REDACClient

  async def submit_batch():
    redac = REDACClient("https://redac.anabrid.com")
    redac.login(username, password)
    with open("config.json", "r") as f:
      config = json.load(f)

    # asynchronously submit three jobs
    jobs = [None, None, None]
    for part_id in range(3):
      job = {        
        "config": config,
        "partition_id": part_id,
        "label": "Job"
      }
      jobs[part_id] = asyncio.create_task(redac.submit_job(job))

    # wait until the three jobs were successfully submitted (and returned their ID)
    for part_id in range(3):
      while not jobs[part_id].done():
        asyncio.sleep(0.5)

    # not wait until the jobs are done (in the meantime, you can do some other work)
    for part_id in range(3):
      job_id = jobs[part_id].result()
      is_done = False

      while not is_done:
        is_done = (await redac.get_job_status(job_id).status == "COMPLETED")
        asyncio.sleep(0.5)

    # finally, download and print results
    for part_id in range(3):
      job_id = jobs[part_id].result()
      results = await redac.get_job_results(job_id)
      print(json.dumps(results))

  if __name__ == "__main__":
    asyncio.run(submit_batch())

Save this script as ``batch.py``, the execute it with ``python batch.py``. If you
are not familiar with the ``async`` syntax used here, please refer to the official
Python developer's documentation.