quantnet-agent 1.0.0__tar.gz

quantnet_agent-1.0.0/LICENSE

@@ -0,0 +1,41 @@
+QUANT-NET Control Plane Framework (QNCP) Copyright (c) 2025, The Regents of the
+University of California, through Lawrence Berkeley National Laboratory (subject
+to receipt of any required approvals from the U.S. Dept. of Energy). All rights
+reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+(1) Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+(2) Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+(3) Neither the name of the University of California, Lawrence Berkeley National
+Laboratory, U.S. Dept. of Energy nor the names of its contributors may be used
+to endorse or promote products derived from this software without specific prior
+written permission.
+
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+You are under no obligation whatsoever to provide any bug fixes, patches, or
+upgrades to the features, functionality or performance of the source code
+("Enhancements") to anyone; however, if you choose to make your Enhancements
+available either publicly, or directly to Lawrence Berkeley National Laboratory,
+without imposing a separate written license agreement for such Enhancements,
+then you hereby grant the following license: a non-exclusive, royalty-free
+perpetual license to install, use, modify, prepare derivative works, incorporate
+into other computer software, distribute, and sublicense such enhancements or
+derivative works thereof, in binary and source code form.

quantnet_agent-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include requirements.txt
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+

quantnet_agent-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: quantnet-agent
+Version: 1.0.0
+Summary: The QN Agent for Quant-Net Control Plane
+Author-email: ESnet <quantum@es.net>
+License-Expression: BSD-3-Clause-LBNL
+Project-URL: Homepage, https://github.com/quant-net/quant-net-agent
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncio-mqtt==0.16.1
+Requires-Dist: click==8.1.3
+Requires-Dist: uvloop==0.21.0
+Requires-Dist: ThorlabsPM100
+Requires-Dist: numpy==1.26.2
+Requires-Dist: pyserial==3.3
+Requires-Dist: configobj==5.0.9
+Requires-Dist: apscheduler==3.10.4
+Requires-Dist: pydantic==2.7.3
+Requires-Dist: pyyaml==6.0.1
+Requires-Dist: networkx==3.4.2
+Requires-Dist: quantnet-mq
+Dynamic: license-file
+
+
+# Quant-Net Agent
+
+The QUANT-NET Control Plane (QNCP) runs as a distributed system. This Agent
+registers resources, interfaces with devices, and interprets protocol commands
+from a Controller instance. The Agent package includes the concept of extensible
+command interpreters, which define the behavior of the Agents when processing
+protocol messages and interacting with the underlying hardware or simulation
+devices.
+
+The Agent includes a hardware abstraction layer (HAL) that defines a base set of
+hardware classes for managing the interaction with quantum devices and external
+experiment control frameworks.
+
+## Development Install
+
+Pull requirements and install package in edit mode. 
+
+```
+pip3 install -e .
+```
+
+The `quantnet_agent` script will be available in your local path, or check `~/.local/bin`
+
+```
+$ quantnet_agent --help
+Usage: quantnet_agent [OPTIONS]
+
+Options:
+  -c, --config TEXT         Main configuration file  [default:
+                            ./config/agent.cfg]
+  -n, --node-config TEXT    Node configuration file  [default: ~/.quant-
+                            net/node.json]
+  -a, --agent_id TEXT       Specify an agent identifier  [default: ]
+  --mq-broker-host TEXT     Message queue broker host
+  --mq-broker-port INTEGER  Message queue broker port
+  -d, --debug               Enable debug logging
+  --interpreter-path TEXT   Location of additional command interpreters
+  --schema-path TEXT        Specify a path containing additional schema files
+  --help                    Show this message and exit.
+```
+
+## Example usage
+
+An MQTT broker should be available for the agent to connect to. A development docker-compose file that starts an Eclipse Mosquitto instance is available in `quant-net-docker:docker-compose-backend.yml`
+
+Testing node config files exist in `quant-net-mq:quant-net-mq/schemas/examples`
+
+Running the agent:
+
+```
+quantnet_agent --mq-broker-host <broker> -n <path_to>/quant-net-mq/quantnet_mq/schema/examples/conf_qnode.json
+```
+
+
+
+

quantnet_agent-1.0.0/README.md

@@ -0,0 +1,57 @@
+
+# Quant-Net Agent
+
+The QUANT-NET Control Plane (QNCP) runs as a distributed system. This Agent
+registers resources, interfaces with devices, and interprets protocol commands
+from a Controller instance. The Agent package includes the concept of extensible
+command interpreters, which define the behavior of the Agents when processing
+protocol messages and interacting with the underlying hardware or simulation
+devices.
+
+The Agent includes a hardware abstraction layer (HAL) that defines a base set of
+hardware classes for managing the interaction with quantum devices and external
+experiment control frameworks.
+
+## Development Install
+
+Pull requirements and install package in edit mode. 
+
+```
+pip3 install -e .
+```
+
+The `quantnet_agent` script will be available in your local path, or check `~/.local/bin`
+
+```
+$ quantnet_agent --help
+Usage: quantnet_agent [OPTIONS]
+
+Options:
+  -c, --config TEXT         Main configuration file  [default:
+                            ./config/agent.cfg]
+  -n, --node-config TEXT    Node configuration file  [default: ~/.quant-
+                            net/node.json]
+  -a, --agent_id TEXT       Specify an agent identifier  [default: ]
+  --mq-broker-host TEXT     Message queue broker host
+  --mq-broker-port INTEGER  Message queue broker port
+  -d, --debug               Enable debug logging
+  --interpreter-path TEXT   Location of additional command interpreters
+  --schema-path TEXT        Specify a path containing additional schema files
+  --help                    Show this message and exit.
+```
+
+## Example usage
+
+An MQTT broker should be available for the agent to connect to. A development docker-compose file that starts an Eclipse Mosquitto instance is available in `quant-net-docker:docker-compose-backend.yml`
+
+Testing node config files exist in `quant-net-mq:quant-net-mq/schemas/examples`
+
+Running the agent:
+
+```
+quantnet_agent --mq-broker-host <broker> -n <path_to>/quant-net-mq/quantnet_mq/schema/examples/conf_qnode.json
+```
+
+
+
+

quantnet_agent-1.0.0/config/logging.conf

@@ -0,0 +1,34 @@
+[loggers]
+keys=root,quantnet_agent,gmqtt
+
+[handlers]
+keys=console
+
+[formatters]
+keys=simple
+
+[logger_root]
+level=INFO
+handlers=console
+
+[logger_quantnet_agent]
+level=DEBUG
+handlers=console
+qualname=agent
+propagate=0
+
+[logger_gmqtt]
+level=CRITICAL
+handlers=console
+qualname=gmqtt
+propagate=0
+
+[handler_console]
+class=StreamHandler
+level=DEBUG
+formatter=simple
+args=(sys.stdout,)
+
+[formatter_simple]
+format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
+datefmt=

quantnet_agent-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantnet-agent"
+authors = [
+  { name="ESnet", email="quantum@es.net" },
+]
+description = "The QN Agent for Quant-Net Control Plane"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "BSD-3-Clause-LBNL"
+license-files = ["LICEN[CS]E*"]
+dynamic = [
+    "version",
+    "dependencies"
+]
+
+[project.urls]
+Homepage = "https://github.com/quant-net/quant-net-agent"
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}
+version = {attr = "quantnet_agent.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["quantnet_agent", "quantnet_agent.*"]
+
+[project.scripts]
+quantnet_agent = "quantnet_agent.cli:main"

quantnet_agent-1.0.0/quantnet_agent/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

quantnet_agent-1.0.0/quantnet_agent/cli.py

@@ -0,0 +1,80 @@
+import socket
+import click
+import sys
+from quantnet_agent.service import QuantnetAgent
+from quantnet_agent.common import Constants, Config
+from quantnet_agent.common.logging import setup_logging
+
+
+@click.command("Quantnet Agent")
+@click.option("-c",
+              "--config",
+              default=Constants.DEFAULT_CONFIG_FILE,
+              help="Main configuration file",
+              show_default=True)
+@click.option("-n",
+              "--node-config",
+              default=None,
+              help="Node configuration file",
+              show_default=True)
+@click.option("-a",
+              "--agent_id",
+              default=socket.getfqdn(),
+              help="Specify an agent identifier",
+              show_default=True)
+@click.option("--mq-broker-host",
+              "mq_broker_host",
+              type=str,
+              help="Message queue broker host",
+              show_default=True)
+@click.option("--mq-broker-port",
+              "mq_broker_port",
+              type=int,
+              help="Message queue broker port",
+              show_default=True)
+@click.option("-d",
+              "--debug",
+              is_flag=True,
+              show_default=True,
+              default=False,
+              help="Enable debug logging")
+@click.option("--interpreter-path",
+              "interpreter_path",
+              type=str,
+              help="Location of additional command interpreters",
+              show_default=True)
+@click.option("--schema-path",
+              "schema_path",
+              type=str,
+              help="Specify a path containing additional schema files",
+              show_default=True
+              )
+def main(config,
+         agent_id,
+         node_config,
+         mq_broker_host,
+         mq_broker_port,
+         debug,
+         interpreter_path,
+         schema_path):
+    cobj = Config(config,
+                  node_config,
+                  debug,
+                  agent_id,
+                  mq_broker_host,
+                  mq_broker_port,
+                  interpreter_path,
+                  schema_path)
+
+    if cobj.node_file is None:
+        print("No node configuration file specified. Use --node-config (-n) to provide one.")
+        sys.exit(1)
+
+    setup_logging(cobj)
+
+    agent = QuantnetAgent(cobj)
+    agent.run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())  # pragma: no cover

quantnet_agent-1.0.0/quantnet_agent/common/__init__.py

@@ -0,0 +1,2 @@
+from .constants import Constants
+from .config import Config

quantnet_agent-1.0.0/quantnet_agent/common/calibration_status.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Calibration_status(Enum):
+    FULL = "Full_scale_calibration"
+    LIGHT = "Lightweight_calibration"
+    CHECK = "Status_check"

quantnet_agent-1.0.0/quantnet_agent/common/config.py

@@ -0,0 +1,135 @@
+import os
+import logging
+import configobj
+import json
+from quantnet_agent.common.constants import Constants
+
+log = logging.getLogger(__name__)
+
+
+def get_config(config_file):
+    config_files = []
+    if config_file:
+        config_files.append(config_file)
+    if "QUANTNET_HOME" in os.environ:
+        config_files.append(f"{os.environ['QUANTNET_HOME']}/etc/agent.cfg")
+    else:
+        config_files.append("/etc/quantnet/agent.cfg")
+
+    for cf in config_files:
+        try:
+            config = configobj.ConfigObj(cf)
+        except IOError:
+            continue
+    return config
+
+
+class Config:
+    def __init__(
+        self,
+        config_file: str = None,
+        node_file: str = None,
+        debug: bool = False,
+        agent_id: str = None,
+        mq_broker_host: str = None,
+        mq_broker_port: int = None,
+        interpreter_path: str = None,
+        schema_path: str = None,
+    ):
+        self._config = None
+        self.devices = {}
+
+        self._config = get_config(config_file)
+
+        if not self._config:
+            log.warning("No configuration file found, continuing with defaults")
+
+        if node_file:
+            self.node_file = node_file
+        else:
+            self.node_file = self.config_get("agent", "node_file", raise_exception=False)
+
+        if mq_broker_host:
+            self.mq_broker_host = mq_broker_host
+        else:
+            self.mq_broker_host = self.config_get("mq", "host", default="127.0.0.1")
+
+        if mq_broker_port:
+            self.mq_broker_port = mq_broker_port
+        else:
+            self.mq_broker_port = self.config_get("mq", "port", default="1883")
+
+        self.threads = int(self.config_get("agent", "threads", default=8))
+
+        if debug:
+            self.debug = debug
+        else:
+            self.config_get("agent", "debug", default=False)
+
+        if agent_id:
+            self.cid = agent_id
+        else:
+            try:
+                self.cid = self.config_get("agent", "agent_id")
+            except Exception:
+                self.cid = None
+
+        if interpreter_path:
+            self.interpreter_path = interpreter_path
+        else:
+            self.interpreter_path = self.config_get("interpreters", "path", raise_exception=False)
+
+        if "protocols" in self._config and len(self._config["protocols"]) > 0:
+            if self.interpreter_path is None:
+                raise Exception("Interpreter location for protocols is not found")
+            self.proto_plugins = self._config["protocols"]
+        else:
+            self.proto_plugins = {}
+
+        if schema_path:
+            self.schema_path = schema_path
+        else:
+            self.schema_path = self.config_get("schemas", "path", raise_exception=False)
+
+        if "devices" in self._config:
+            self.devices = self._config["devices"]
+
+        self.tasks = []
+        self.task_properties = {}
+
+        if "tasks" in self._config:
+            for task, property in self._config["tasks"].items():
+                try:
+                    if type(property) is configobj.Section:
+                        with open(os.path.join(Constants.DEFAULT_TASK_PATH, property["path"]), "r") as file:
+                            calibration_task = json.load(file)
+                            if float(calibration_task["Periodicity"]) <= Constants.SLOTSIZE.total_seconds():
+                                raise Exception(
+                                    f"Task {task} interval is too short."
+                                    "It should be larger than the TDMA slot size "
+                                    f"{Constants.SLOTSIZE.total_seconds() * 1e3 }"
+                                )
+                            self.tasks.append(calibration_task)
+                    else:
+                        self.task_properties[task] = property
+                except Exception as e:
+                    log.error(f"Cannot load local task {task} : {e}")
+
+    def config_get(self, section, option, raise_exception=True, default=None, check_config_table=True):
+        """
+        Return the string value for a given option in a section
+
+        :param section: the named section.
+        :param option: the named option.
+        :param raise_exception: Boolean to raise or not NoOptionError or NoSectionError.
+        :param default: the default value if not found.
+        :param check_config_table: if not set, avoid looking at config table
+        .
+        :returns: the configuration value.
+        """
+        try:
+            return self._config[section][option]
+        except (configobj.ConfigObjError, KeyError) as err:
+            if raise_exception and default is None:
+                raise err
+            return default

quantnet_agent-1.0.0/quantnet_agent/common/constants.py

@@ -0,0 +1,28 @@
+import os
+from datetime import timedelta
+import quantnet_agent
+
+
+class Constants:
+    DEFAULT_CONFIG_FILE = "./config/agent.cfg"
+    DEFAULT_NODE_CONFIG_FILE = "./config/conf-alice.json"
+    DEFAULT_LOGGING_CONFIG_FILE = "./config/logging.conf"
+    DEFAULT_INTERPRETERS = {
+        "scheduler": "scheduler.py",
+        "calibration": "calibration.py",
+        "experiment": "exp_framework.py",
+    }
+    DEFAULT_TASK_PATH = os.path.join(os.path.dirname(os.path.dirname(quantnet_agent.__file__)), "config/")
+    DEFAULT_TASK_INTERPRETER = os.path.join(
+        os.path.dirname(quantnet_agent.__file__), "hal/interpreter/calibration_interpreter.py"
+    )
+    DEFAULT_TASK_NS = "quantnet_agent.task"
+    HEARTBEAT_INTERVAL = 10
+    REGISTRATION_RETRY_INTERVAL = 10
+    MAX_TIMESLOTS = 20000
+    SLOTSIZE = timedelta(milliseconds=100)
+    SCHEDULER_GRACE_PERIOD = timedelta(milliseconds=50)
+    # TODO: Check SCHEDULER_GRACE_PERIOD < SLOTSIZE * MAX_TIMESLOTS
+    UPDATE_INTERVAL = SLOTSIZE * MAX_TIMESLOTS / 2
+    # TODO: Check if update_interval is appropriate
+    DAG_CHECK_INTERVAL = timedelta(milliseconds=1000)

quantnet_agent-1.0.0/quantnet_agent/common/logging.py

@@ -0,0 +1,60 @@
+import os
+import sys
+import logging
+import logging.config
+
+
+def quantnet_log_formatter(cobj=None):
+    config_logformat = cobj.config_get(
+        "common",
+        "logformat",
+        raise_exception=False,
+        default="{asctime} {name:<29} {process} {levelname:>8} {message}",
+    )
+    return logging.Formatter(fmt=config_logformat, style='{')
+
+
+def setup_default_logging(cobj=None):
+    """
+    Configures the logging by setting the output stream to stdout and
+    configures log level and log format.
+    """
+    config_loglevel = getattr(logging, cobj.config_get("common", "loglevel",
+                              raise_exception=False, default="INFO").upper())
+
+    stdouthandler = logging.StreamHandler(stream=sys.stdout)
+    stdouthandler.setFormatter(quantnet_log_formatter(cobj))
+    stdouthandler.setLevel(config_loglevel)
+    logging.basicConfig(level=config_loglevel, handlers=[stdouthandler])
+
+
+def setup_logging(cobj=None):
+    """
+    Configures the logging by setting the output stream to stdout and
+    configures log level and log format.
+    """
+
+    configfiles = list()
+
+    if cobj:
+        logging_config_path = cobj.config_get("common", "logging_config", raise_exception=False, default=None)
+        if logging_config_path:
+            configfiles.append(logging_config_path)
+
+    for i in ["QUANTNET_HOME", "VIRTUAL_ENV"]:
+        if i in os.environ:
+            configfiles.append(f"{os.environ[i]}/etc/logging.conf")
+    configfiles.append("/opt/quantnet/etc/logging.conf")
+
+    has_config = False
+    for configfile in configfiles:
+        try:
+            logging.config.fileConfig(configfile, disable_existing_loggers=False)
+            has_config = True
+        except Exception:
+            has_config = False
+        if has_config:
+            break
+
+    if not has_config and cobj:
+        setup_default_logging(cobj)