Rn d

.github/workflows/validation.yml

@@ -15,7 +15,6 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.11"
           - "3.12"
           - "3.13"
           - "3.14"

CHANGELOG.md

@@ -5,11 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-3-02
+### Added
+- Added the `routing` module: a new parent class `RoutingProtocol` for the subclasses `StaticRoutingProtocol` and `DistributedRoutingProtocol`. The register decorator is used to make it easy to plug in new routing protocols in the future.
+- Add empty init() to Protocol to satisfy class hierarchy.
+- Created project scripts for each config generator.
+- Added the `swapping` module that has the following classes. The subclasses use the registry decorator (factory pattern).
+    - Base class: `EntanglementSwappingA` & `EntanglementSwappingB`
+    - Subclass for ket vector and density matrix: `EntanglementSwappingA_Circuit` & `EntanglementSwappingB_Circuit`
+    - Subclass for Bell diagonal state: `EntanglementSwappingA_BDS` & `EntanglementSwappingB_BDS`
+- Update the tutorial to catch up on the recent updates. Add notes saying refer to chapter 6 Application module for standard usage
+- Introducing `EARLY_EXPIRE` message type. A request has a `start_time` and `end_time`. When a request is finished before the `end_time`, then the reservation (and the associated rules) should expire early. If not, the quantum network will keep generating entanglement pairs because the rules still exist.
+
+### Changed
+- Docstring, comment, logging, and various cosmetic updates.
+- Moved routing_protocol init() to network manager.
+- Trigger empty inits for resource and network manager to enable future bootstrapping.
+- Migrated `utils/json_config_generators/` to `sequence/config_generators/`.
+
+### Removed
+- The old `swapping.py` is removed.
+
+
 ## [0.8.5] - 2026-2-27
 ### Added
 - `NetworkManager` ABC with a factory pattern for selection and future implementation of new network managers.
 - File `action_condition_set.py` is added. This contains the action, condition, and request functions for entanglement generation, swapping, and purification.
-- Class `DistributedRoutingProtocol` is added, among many other supporting classes in `routing_distributed.py`. This module does distributed entanglement routing.
+- Class `DistributedRoutingProtocol` is added, among many other supporting classes in `routing_distributed`. This module does distributed entanglement routing.
 - Class `NetworkManager` has two new attributes: `forwarding_table` and `routing_protocol`.
 - Add a cutoff flag to memory to allow disable the expiration of memories.
 - Add a template in config json for network manager to select routing protocols (distributed vs. static)

README.md

@@ -38,7 +38,7 @@ These modules can be edited by users to define additional functionality and test
 
 ## Installation
 ### For Users
-SeQUeNCe requires [Python](https://www.python.org/downloads/) 3.11 or later. You can install SeQUeNCe using `pip`:
+SeQUeNCe requires [Python](https://www.python.org/downloads/) 3.12 or later. You can install SeQUeNCe using `pip`:
 ```
 pip install sequence
 ```

docs/source/tutorial/chapter0/prerequisite.md

@@ -6,7 +6,7 @@ Thank you for downloading SeQUeNCe and welcome to the tutorial section of the do
 
 ### Python Version
 
-The simulator requires at least version **3.10** of Python. This can be found at the [Python Website](https://www.python.org/downloads/).
+The simulator requires at least version **3.11** of Python. This can be found at the [Python Website](https://www.python.org/downloads/).
 
 ### Dependencies
 

docs/source/tutorial/chapter1/discrete-event-simulation.md

@@ -65,7 +65,7 @@ tl.show_progress = False # turn of progress bar, we will address this in later t
 store = Store(tl) # create store
 
 # open store at 7:00
-open_proc = Process(store, 'open', []) # Process(object, function name: string, arguments of function: List[])
+open_proc = Process(store, 'open', []) # Process(object, function name: string, arguments of function: list[])
 open_event = Event(7, open_proc) # Event(occurring time: int, process: Process)
 tl.schedule(open_event) # Timeline.schedule(Event)
 ```

docs/source/tutorial/chapter3/entangle.md

@@ -1,5 +1,9 @@
 # Chapter 3: Entanglement Management
 
+**NOTE**: The standard way to generate entanglement is to use the `app` module, which is discussed in chapter 6. The purpose of this chapter is to explain what is happening under the hood in the entanglement management module. 
+
+---
+
 In previous chapters, we introduced the usage of hardware models. 
 In this chapter, we will use protocols in the entanglement management module to control these hardware devices and change the entanglement state of quantum memories.
 We will also use a simple manager protocol to control the entanglement generation protocols.
@@ -515,10 +519,11 @@ class SimpleManager:
         if type(self.owner) is SwapNodeA:
             left_memo = self.owner.components[self.memo_names[0]]
             right_memo = self.owner.components[self.memo_names[1]]
-            self.owner.protocols = [EntanglementSwappingA(self.owner, 'ESA', left_memo, right_memo, 1, 0.99)]
+            self.owner.protocols = [EntanglementSwappingA.create(self.owner, 'ESA', left_memo, right_memo, 
+                                                                 success_prob=1, degradation=0.99)]
         else:
             memo = self.owner.components[self.memo_names[0]]
-            self.owner.protocols = [EntanglementSwappingB(self.owner, '%s.ESB' % self.owner.name, memo)]
+            self.owner.protocols = [EntanglementSwappingB.create(self.owner, '%s.ESB' % self.owner.name, memo)]
 ```
 
 ### Step 2: Create Network

docs/source/tutorial/chapter3/example3.py

@@ -24,10 +24,11 @@ def create_protocol(self):
         if type(self.owner) is SwapNodeA:
             left_memo = self.owner.components[self.memo_names[0]]
             right_memo = self.owner.components[self.memo_names[1]]
-            self.owner.protocols = [EntanglementSwappingA(self.owner, 'ESA', left_memo, right_memo, 1, 0.99)]
+            self.owner.protocols = [EntanglementSwappingA.create(self.owner, 'ESA', left_memo, right_memo, 
+                                                                 success_prob=1, degradation=0.99)]
         else:
             memo = self.owner.components[self.memo_names[0]]
-            self.owner.protocols = [EntanglementSwappingB(self.owner, '%s.ESB' % self.owner.name, memo)]
+            self.owner.protocols = [EntanglementSwappingB.create(self.owner, '%s.ESB' % self.owner.name, memo)]
 
 
 class SwapNodeA(Node):
@@ -59,7 +60,7 @@ def receive_message(self, src: str, msg: "Message") -> None:
         self.protocols[0].received_message(src, msg)
 
     def create_protocol(self):
-        self.protocols = [EntanglementSwappingB(self, '%s.ESB'%self.name, self.memo)]
+        self.protocols = [EntanglementSwappingB.create(self, '%s.ESB'%self.name, self.memo)]
 
 
 def entangle_memory(tl: Timeline, memo1: Memory, memo2: Memory, fidelity: float):

docs/source/tutorial/chapter4/resource_management.md

@@ -1,5 +1,11 @@
 # Chapter 4: Resource Management
 
+**NOTE**: The standard way to generate entanglement is to use the `app` module, which is discussed in chapter 6. The purpose of this chapter is to explain what is happening under the hood in the resource management module. 
+
+See `sequence.resource_management.action_condition_set` for detailed docstrings.
+
+---
+
 In this tutorial, we will show the usual operation of the Resource Management module included in SeQUeNCe. We’re going to build a linear, three-node network and create two entanglement flows. The network, including flows, is shown below:
 
 ![topo](figures/two_flow_linear_topo.png)
@@ -145,26 +151,25 @@ def eg_match_func(protocols, args):
 def eg_rule_action_await(memories_info: List["MemoryInfo"], args):
     mid_name = args["mid_name"]
     other_name = args["other_name"]
-
     memories = [info.memory for info in memories_info]
     memory = memories[0]
-    protocol = EntanglementGenerationA(None, "EGA." + memory.name, mid_name,
-                                       other_name,
-                                       memory)
-    req_args = {"remote_node": args["node_name"],
-                "index_upper": args["index_upper"],
-                "index_lower": args["index_lower"]}
-    return [protocol, [other_name], [eg_match_func], [req_args]]
+    protocol = EntanglementGenerationA.create(None, "EGA." + memory.name,
+                                              mid_name, other_name, memory)
+    return [protocol, [None], [None], [None]]
 
 
 def eg_rule_action_request(memories_info: List["MemoryInfo"], args):
     mid_name = args["mid_name"]
     other_name = args["other_name"]
+
     memories = [info.memory for info in memories_info]
     memory = memories[0]
-    protocol = EntanglementGenerationA(None, "EGA." + memory.name,
-                                       mid_name, other_name, memory)
-    return [protocol, [None], [None], [None]]
+    protocol = EntanglementGenerationA.create(None, "EGA." + memory.name, 
+                                              mid_name, other_name, memory)
+    req_args = {"remote_node": args["node_name"],
+                "index_upper": args["index_upper"],
+                "index_lower": args["index_lower"]}
+    return [protocol, [other_name], [eg_match_func], [req_args]]
 ```
 
 ### Step 4: Build the Network
@@ -230,10 +235,10 @@ tl.init()
 action_args = {"mid_name": "m12", "other_name": "r2", "node_name": "r1",
                "index_upper": 9, "index_lower": 0}
 condition_args = {"index_lower": 0, "index_upper": 9}
-rule1 = Rule(10, eg_rule_action_await, eg_rule_condition, action_args, condition_args)
+rule1 = Rule(10, eg_rule_action_request, eg_rule_condition, action_args, condition_args)
 r1.resource_manager.load(rule1)
 action_args2 = {"mid_name": "m12", "other_name": "r1"}
-rule2 = Rule(10, eg_rule_action_request, eg_rule_condition, action_args2, condition_args)
+rule2 = Rule(10, eg_rule_action_await, eg_rule_condition, action_args2, condition_args)
 r2.resource_manager.load(rule2)
 
 tl.run()
@@ -262,8 +267,7 @@ To do this, we'll create a function `add_eg_rules` that takes as arguments
 - `path`, a list of router nodes that make up the path of the entanglement flow, and
 - `middles`, a list of bsm nodes along the path.
 
-The conditions and actions of the rule will be very similar to before, but with variable memory indices, nodes, and
-arguments.
+The conditions and actions of the rule will be very similar to before, but with variable memory indices, nodes, and arguments.
 
 ```python
 def add_eg_rules(index: int, path: List[RouterNode], middles: List[BSMNode]):
@@ -281,8 +285,7 @@ def add_eg_rules(index: int, path: List[RouterNode], middles: List[BSMNode]):
         condition_args = {"index_lower": mem_range[0],
                           "index_upper": mem_range[0] + 9}
 
-        rule = Rule(10, eg_rule_action_request, eg_rule_condition, action_args,
-                    condition_args)
+        rule = Rule(10, eg_rule_action_await, eg_rule_condition, action_args, condition_args)
         node.resource_manager.load(rule)
 
     if index < (len(path) - 1):
@@ -299,14 +302,8 @@ def add_eg_rules(index: int, path: List[RouterNode], middles: List[BSMNode]):
                        "index_upper": node_mems[index + 1][1] - 1,
                        "index_lower": node_mems[index + 1][0]}
 
-        memories = [info.memory for info in memories_info]
-        memory = memories[0]
-        protocol = EntanglementGenerationA(None, "EGA." + memory.name, middle_names[index], node_names[index + 1],
-                                           memory)
-        return [protocol, [node_names[index + 1]], [req_func]]
-
-    rule = Rule(10, eg_rule_action, eg_rule_condition)
-    node.resource_manager.load(rule)
+        rule = Rule(10, eg_rule_action_request, eg_rule_condition, action_args, condition_args)
+        node.resource_manager.load(rule)
 ```
 
 ### Step 7: Flow 2 Entanglement Purification
@@ -320,10 +317,9 @@ The arguments for our `add_ep_rules` function will be similar to our previous fu
 - `target_fidelity`, the fidelity of entanglement we wish to achieve.
 
 ```python
-from sequence.entanglement_management.purification import BBPSSW
+from sequence.entanglement_management.purification import BBPSSWProtocol
 
-def ep_rule_condition_request(memory_info: "MemoryInfo", manager: "MemoryManager",
-                       args):
+def ep_rule_condition_request(memory_info: "MemoryInfo", manager: "MemoryManager", args):
     index_upper = args["index_upper"]
     index_lower = args["index_lower"]
     target_fidelity = args["target_fidelity"]
@@ -346,7 +342,7 @@ def ep_match_func(protocols, args):
 
     _protocols = []
     for protocol in protocols:
-        if not isinstance(protocol, BBPSSW):
+        if not isinstance(protocol, BBPSSWProtocol):
             continue
 
         if protocol.kept_memo.name == remote1:
@@ -361,10 +357,8 @@ def ep_match_func(protocols, args):
     _protocols[1].rule.protocols.remove(_protocols[1])
     _protocols[1].kept_memo.detach(_protocols[1])
     _protocols[0].meas_memo = _protocols[1].kept_memo
-    _protocols[0].memories = [_protocols[0].kept_memo,
-                              _protocols[0].meas_memo]
-    _protocols[0].name = _protocols[0].name + "." + _protocols[
-        0].meas_memo.name
+    _protocols[0].memories = [_protocols[0].kept_memo, _protocols[0].meas_memo]
+    _protocols[0].name = _protocols[0].name + "." + _protocols[0].meas_memo.name
     _protocols[0].meas_memo.attach(_protocols[0])
 
     return _protocols[0]
@@ -373,16 +367,15 @@ def ep_match_func(protocols, args):
 def ep_rule_action_request(memories_info: List["MemoryInfo"], args):
     memories = [info.memory for info in memories_info]
     name = "EP.%s.%s" % (memories[0].name, memories[1].name)
-    protocol = BBPSSW(None, name, memories[0], memories[1])
+    protocol = BBPSSWProtocol.create(None, name, memories[0], memories[1])
     dsts = [memories_info[0].remote_node]
     req_funcs = [ep_match_func]
     req_args = {"remote1": memories_info[0].remote_memo,
                 "remote2": memories_info[1].remote_memo}
     return [protocol, dsts, req_funcs, [req_args]]
 
 
-def ep_rule_condition_await(memory_info: "MemoryInfo", manager: "MemoryManager",
-                       args):
+def ep_rule_condition_await(memory_info: "MemoryInfo", manager: "MemoryManager", args):
     index_upper = args["index_upper"]
     index_lower = args["index_lower"]
     target_fidelity = args["target_fidelity"]
@@ -395,7 +388,7 @@ def ep_rule_condition_await(memory_info: "MemoryInfo", manager: "MemoryManager",
 def ep_rule_action_await(memories_info: List["MemoryInfo"], args):
     memories = [info.memory for info in memories_info]
     name = "EP.%s" % (memories[0].name)
-    protocol = BBPSSW(None, name, memories[0], None)
+    protocol = BBPSSWProtocol.create(None, name, memories[0], None)
     return [protocol, [None], [None], [None]]
 
 
@@ -437,8 +430,7 @@ For now, we will only define the actions and conditions and leave the rule creat
 ```python
 from sequence.entanglement_management.swapping import EntanglementSwappingA, EntanglementSwappingB
 
-def es_rule_condition_A(memory_info: "MemoryInfo", manager: "MemoryManager",
-                       args):
+def es_rule_condition_A(memory_info: "MemoryInfo", manager: "MemoryManager", args):
     index_lower = args["index_lower"]
     index_upper = args["index_upper"]
     target_fidelity = args["target_fidelity"]
@@ -481,20 +473,17 @@ def es_rule_action_A(memories_info: List["MemoryInfo"], args):
 
     memories = [info.memory for info in memories_info]
 
-    protocol = EntanglementSwappingA(None, "ESA.%s.%s" % (
-        memories[0].name, memories[1].name),
-                                     memories[0], memories[1],
-                                     success_prob=succ_prob,
-                                     degradation=degradation)
+    protocol_name = "ESA.%s.%s" % (memories[0].name, memories[1].name)
+    protocol = EntanglementSwappingA.create(None, protocol_name, memories[0], memories[1], 
+                                            success_prob=succ_prob, degradation=degradation)
     dsts = [info.remote_node for info in memories_info]
     req_funcs = [es_match_func, es_match_func]
     req_args = [{"target_memo": memories_info[0].remote_memo},
                 {"target_memo": memories_info[1].remote_memo}]
     return [protocol, dsts, req_funcs, req_args]
 
 
-def es_rule_condition_B(memory_info: "MemoryInfo", manager: "MemoryManager",
-                       args):
+def es_rule_condition_B(memory_info: "MemoryInfo", manager: "MemoryManager", args):
     index_lower = args["index_lower"]
     index_upper = args["index_upper"]
     target_node = args["target_node"]
@@ -512,7 +501,7 @@ def es_rule_condition_B(memory_info: "MemoryInfo", manager: "MemoryManager",
 def es_rule_action_B(memories_info: List["MemoryInfo"], args):
     memories = [info.memory for info in memories_info]
     memory = memories[0]
-    protocol = EntanglementSwappingB(None, "ESB." + memory.name, memory)
+    protocol = EntanglementSwappingB.create(None, "ESB." + memory.name, memory)
     return [protocol, [None], [None], [None]]
 ```
 

docs/source/tutorial/chapter4/two_flow.py

@@ -177,10 +177,8 @@ def ep_req_func(protocols, args):
     _protocols[1].rule.protocols.remove(_protocols[1])
     _protocols[1].kept_memo.detach(_protocols[1])
     _protocols[0].meas_memo = _protocols[1].kept_memo
-    _protocols[0].memories = [_protocols[0].kept_memo,
-                              _protocols[0].meas_memo]
-    _protocols[0].name = _protocols[0].name + "." + _protocols[
-        0].meas_memo.name
+    _protocols[0].memories = [_protocols[0].kept_memo,_protocols[0].meas_memo]
+    _protocols[0].name = _protocols[0].name + "." + _protocols[0].meas_memo.name
     _protocols[0].meas_memo.attach(_protocols[0])
 
     return _protocols[0]
@@ -288,11 +286,9 @@ def es_rule_actionA(memories_info: list["MemoryInfo"], args):
 
     memories = [info.memory for info in memories_info]
 
-    protocol = EntanglementSwappingA(None, "ESA.%s.%s" % (
-        memories[0].name, memories[1].name),
-                                     memories[0], memories[1],
-                                     success_prob=succ_prob,
-                                     degradation=degradation)
+    protocol_name = "ESA.%s.%s" % (memories[0].name, memories[1].name)
+    protocol = EntanglementSwappingA.create(None, protocol_name, memories[0], memories[1],
+                                            success_prob=succ_prob, degradation=degradation)
     dsts = [info.remote_node for info in memories_info]
     req_funcs = [es_req_func, es_req_func]
     req_args = [{"target_memo": memories_info[0].remote_memo},
@@ -318,7 +314,7 @@ def es_rule_conditionB(memory_info: "MemoryInfo", manager: "MemoryManager", args
 def es_rule_actionB(memories_info: list["MemoryInfo"], args):
     memories = [info.memory for info in memories_info]
     memory = memories[0]
-    protocol = EntanglementSwappingB(None, "ESB." + memory.name, memory)
+    protocol = EntanglementSwappingB.create(None, "ESB." + memory.name, memory)
     return [protocol, [None], [None], [None]]
 
 

docs/source/tutorial/chapter5/network_manager.md

@@ -1,10 +1,15 @@
 # Chapter 5: Network Manager
 
-In this tutorial, we will showcase the Network Management module of SeQUeNCe and show its operation on a typical network. The goal of this tutorial is to
+**NOTE**: The standard way to generate entanglement is to use the `app` module, which is discussed in chapter 6. The purpose of this chapter is to explain what is happening under the hood in the network management module. 
+
+---
+
+In this tutorial, we will showcase the (default and distributed) Network Management module of SeQUeNCe and show its operation on a typical network. The goal of this tutorial is to
 - Gain familiarity with the `network_management` module
 - Gain familiarity with the `topology.topology` module
 - Using external files to build networks
 
+
 To achieve this, we will be using an example json file to build our network and will use the network manager on `QuantumRouter` nodes to request entanglement pairs. The json file will create the network topology shown below:
 
 ![topo](figures/star_network.png)