From 42de1cfaf6d4015e6a4af30320fa4b1def1e55b6 Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Thu, 19 Feb 2026 18:18:08 -0800 Subject: [PATCH 1/8] discrete event CEP --- source/cep/cep31.rst | 127 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 source/cep/cep31.rst diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst new file mode 100644 index 00000000..553e8293 --- /dev/null +++ b/source/cep/cep31.rst @@ -0,0 +1,127 @@ +CEP 31 - Agent Registered Discrete Event Timing +*********************************************************** + +:CEP: 31 +:Title: Agent Registered Discrete Event Timing +:Last-Modified: 2026-02-19 +:Author: Meghan Krieg +:Status: Draft +:Type: Standards Track +:Created: Paul Wilson + +Background +=========== + +|Cyclus| currently runs using a fixed increment time advancement mechanism, ``dt``. +Within each ``dt`` of the simulation, |cyclus's| cardinal function progresses through a distinct ordering +of 6 phases which include the + +- Building Phase +- Tick Phase +- Exchange Phase +- Tock Phase +- Decision Phase +- Decomissioning Phase + +before advancing to the next time step. One of the core paradigms of this implementation is +that all agents within the simulation must participate in the Dynamic Resource Exchange and +the surrounding time execution steps (Tick/Tock phases). The ordering of these phases allows +the maxiumum transition of resources with building phase completed first and decomissioning last. +In addition to this feature, the phase ordering toggles between two categories: agent phase nad kernel phase. +While the kernel phase represents events that alter the simulation state, agent phases include +actions that update an agent's internal state. For more information, refer to ---. + +Where --- defined |cyclus| as a broadly discrete event simulation, CEP 31 will push the implementation +further. + +Motivation and Rationale +========================== + +Simulations with event based or discrete event timing run on an internal clock rather than a fixed simulation +clock (as featured in |cyclus|). For this internal clock, events that alter the simulation state are registered at distinct timestamps +within the simulation duration. The simulation progresses from scheduled event to scheduled event skipping timestamps +where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. +Then, the timeline for a 10 month simulation will proceed as follows + + +START 3 (build) -- 5 (trade) -- 7 (decom) END + +as opposed to the current implementation + +START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END + +In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory +and status to register themselves for DRE participation, Build, or Decomission events. In instances +when no agents reigster actions, there will be no events, and the simulation will skip that timestmap. Agents will +dicate the dynamics of the simulation instead of a fixed timestep forcing interactions. + +With many timesteps skipped between agent's cycle/event registrations, computational time will be lower. + +Conceptualization +=============================== + +Based on the current structure set up by the kernal and agent steps in the phase suit, the following +discrete event implementation is suggested... + +Events in the simulation's internal clock can be requested by agents using their own `EventRequest()` function. +Events may only be registered when agents wish to complete the follwing actions: + +- Build +- Request Materials +- Decomission + +These actions map to the current *kernel* phases of |cyclus's| cardinal function. Thus, by extent, + +- Tick +- Tock +- Decision + +may not be considered events because they do *not* change the simulation state. They change +the agent's internal state (agent phase). As these actions are not events, they may never be independently registered by agents. +(There are scenarios in which build/requets/decomission may trigger them, however.) + +For the DRE, agents will *only* be able to register for material requests; thus, material demands instead of material +supply will drive the DRE scheduling. When agents go to register an event by requesting a material, they are unaware of the state of other agent's +supplies. So, for the subset of agents that are triggering DRE events through material requests, *all available +agents in the simulation must be accessible to the DRE to request bids and responses*. This ensures that material request events aren't prohibited from being satisfied +even when requested material exists. + +Because of the required attendance for all agents in the material bids stage of the DRE, the agent phases Tick/Tock/Decision must be triggered +for all available agents as well. These internal Tick/Tock/Decision updates are crucial for deriving accurate *bid* information for request portfolios. There are further +filtering options that consider deregistering an agent's Tocks/Decisions when they make no material bids. + +Implementation ++++++++++++++++++++++++ + +Material requests, Build, and Decomissioin event registration will be handled by individual agents. |Cyclus| already creates a preconditioned timeline +for discrete-build and decomission events. An additional `EventRequest()` member funcition for all |cycamore| archetypes will check a facility's inventory. + +1. If inventory not at capacity, agent will register for the (+1) next immediate time step to attempt another request. +2. If inventory at capacity, agent will register its next request event for a fixed `+ cycle_length` time in from the current event. + +These material request events will be registered within Context in a dynamic dictionary that contains the event's timestamp and a list of ``Trader`` objects. To ensure that all +facility agents' `EventRequest()` functions are checked regularly, A look-ahead function will be added to |cyclus's| cardinal phase suite after the decomissioning phase. + +.. code-block:: c++ + DoBuild(); + DoTick(); + DoResEx(&matl_manager, &genrsrc_manager); + DoTock(); + DoDecision(); + DoDecom(); + DoLookAhead(); + +The cardinal phase suite will maintain its current ordering for the reasons described in ---. Each of the 6 phases will be checked during each event (as opposed to each time step) but the phase will +only be triggered and completed if it has participants registered. Only the newly introduced `DoLookAhead()` that checks each agents `EventRequest()` will be executed for all agents each event. + +The simulation will be terminated fully when `DoLookAhead()` registers no new events and the simulation has completed the last event registered. + +Backwards Compatibility +======================== + +These changes will not be backwards compatible with |cyclus| v1.6.0 and may require a new release. An optional simulation parameter could be introduced to switch this treatment on and off +such that the original time implemenation can be used. + + + + From 70c925c67ab3a270e4dc4066f3bb69645cf85fb7 Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Thu, 19 Feb 2026 18:28:19 -0800 Subject: [PATCH 2/8] better formatting --- source/cep/cep31.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index 553e8293..3da6c66c 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -43,12 +43,13 @@ within the simulation duration. The simulation progresses from scheduled event t where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows - -START 3 (build) -- 5 (trade) -- 7 (decom) END +centered:: + START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation -START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END +centered:: + START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory and status to register themselves for DRE participation, Build, or Decomission events. In instances @@ -63,7 +64,7 @@ Conceptualization Based on the current structure set up by the kernal and agent steps in the phase suit, the following discrete event implementation is suggested... -Events in the simulation's internal clock can be requested by agents using their own `EventRequest()` function. +Events in the simulation's internal clock can be requested by agents using their own ``EventRequest()`` function. Events may only be registered when agents wish to complete the follwing actions: - Build @@ -91,16 +92,16 @@ for all available agents as well. These internal Tick/Tock/Decision updates are filtering options that consider deregistering an agent's Tocks/Decisions when they make no material bids. Implementation -+++++++++++++++++++++++ +=============================== Material requests, Build, and Decomissioin event registration will be handled by individual agents. |Cyclus| already creates a preconditioned timeline -for discrete-build and decomission events. An additional `EventRequest()` member funcition for all |cycamore| archetypes will check a facility's inventory. +for discrete-build and decomission events. An additional ``EventRequest()`` member funcition for all |cycamore| archetypes will check a facility's inventory. 1. If inventory not at capacity, agent will register for the (+1) next immediate time step to attempt another request. -2. If inventory at capacity, agent will register its next request event for a fixed `+ cycle_length` time in from the current event. +2. If inventory at capacity, agent will register its next request event for a fixed ``+ cycle_length`` time from the current event. These material request events will be registered within Context in a dynamic dictionary that contains the event's timestamp and a list of ``Trader`` objects. To ensure that all -facility agents' `EventRequest()` functions are checked regularly, A look-ahead function will be added to |cyclus's| cardinal phase suite after the decomissioning phase. +facility agents' ``EventRequest()`` functions are checked regularly, A look-ahead function will be added to |cyclus's| cardinal phase suite after the decomissioning phase. .. code-block:: c++ DoBuild(); @@ -112,9 +113,9 @@ facility agents' `EventRequest()` functions are checked regularly, A look-ahead DoLookAhead(); The cardinal phase suite will maintain its current ordering for the reasons described in ---. Each of the 6 phases will be checked during each event (as opposed to each time step) but the phase will -only be triggered and completed if it has participants registered. Only the newly introduced `DoLookAhead()` that checks each agents `EventRequest()` will be executed for all agents each event. +only be triggered and completed if it has participants registered. Only the newly introduced ``DoLookAhead()`` that checks each agents ``EventRequest()`` will be executed for all agents each event. -The simulation will be terminated fully when `DoLookAhead()` registers no new events and the simulation has completed the last event registered. +The simulation will be terminated fully when ``DoLookAhead()`` registers no new events and the simulation has completed the last event registered. Backwards Compatibility ======================== From eff0d519b4f3b18e03b4e241b1a84a7c733637ff Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Thu, 19 Feb 2026 18:29:18 -0800 Subject: [PATCH 3/8] better formatting --- source/cep/cep31.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index 3da6c66c..48fccfe1 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -43,12 +43,12 @@ within the simulation duration. The simulation progresses from scheduled event t where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows -centered:: +.. centered:: START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation -centered:: +.. centered:: START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory From d18f14c626858446c765531a0d2b46873e03f746 Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Fri, 20 Feb 2026 08:32:35 -0800 Subject: [PATCH 4/8] centering --- source/cep/cep31.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index 48fccfe1..04e2195f 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -43,12 +43,12 @@ within the simulation duration. The simulation progresses from scheduled event t where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows -.. centered:: +.. :: START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation -.. centered:: +.. :: START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory From 225fc38a3501cb9a9a4fa31e9794442e4771a0fb Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Fri, 20 Feb 2026 08:34:01 -0800 Subject: [PATCH 5/8] centering --- source/cep/cep31.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index 04e2195f..f632aab1 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -43,12 +43,12 @@ within the simulation duration. The simulation progresses from scheduled event t where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows -.. :: +.. class:: center START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation -.. :: +.. class:: center START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory From 62b9367b821a84fc1e8f1864035805741a600cee Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Fri, 20 Feb 2026 09:44:52 -0800 Subject: [PATCH 6/8] adding hyperlinks --- source/cep/cep31.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index f632aab1..e6ab2c65 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -5,15 +5,17 @@ CEP 31 - Agent Registered Discrete Event Timing :Title: Agent Registered Discrete Event Timing :Last-Modified: 2026-02-19 :Author: Meghan Krieg +:BDFP: Madicken Munk/Paul Wilson :Status: Draft :Type: Standards Track -:Created: Paul Wilson +:Created: 2026-02-20 +:Cyclus-Version: 1.6.0 Background =========== |Cyclus| currently runs using a fixed increment time advancement mechanism, ``dt``. -Within each ``dt`` of the simulation, |cyclus's| cardinal function progresses through a distinct ordering +Within each ``dt`` of the simulation, cyclus's cardinal function progresses through a distinct ordering of 6 phases which include the - Building Phase @@ -29,29 +31,29 @@ the surrounding time execution steps (Tick/Tock phases). The ordering of these p the maxiumum transition of resources with building phase completed first and decomissioning last. In addition to this feature, the phase ordering toggles between two categories: agent phase nad kernel phase. While the kernel phase represents events that alter the simulation state, agent phases include -actions that update an agent's internal state. For more information, refer to ---. +actions that update an agent's internal state. For more information, refer to `CEP 20`_. -Where --- defined |cyclus| as a broadly discrete event simulation, CEP 31 will push the implementation +Where `CEP 20`_ defined cyclus as a broadly discrete event simulation, CEP 31 will push the implementation further. Motivation and Rationale ========================== Simulations with event based or discrete event timing run on an internal clock rather than a fixed simulation -clock (as featured in |cyclus|). For this internal clock, events that alter the simulation state are registered at distinct timestamps +clock (as featured in cyclus). For this internal clock, events that alter the simulation state are registered at distinct timestamps within the simulation duration. The simulation progresses from scheduled event to scheduled event skipping timestamps where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows .. class:: center - START 3 (build) -- 5 (trade) -- 7 (decom) END +START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation .. class:: center - START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END +START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END -In |cyclus|, discrete even timing can be implemented by allowing agents to internally check their inventory +In cyclus, discrete even timing can be implemented by allowing agents to internally check their inventory and status to register themselves for DRE participation, Build, or Decomission events. In instances when no agents reigster actions, there will be no events, and the simulation will skip that timestmap. Agents will dicate the dynamics of the simulation instead of a fixed timestep forcing interactions. @@ -71,7 +73,7 @@ Events may only be registered when agents wish to complete the follwing actions: - Request Materials - Decomission -These actions map to the current *kernel* phases of |cyclus's| cardinal function. Thus, by extent, +These actions map to the current *kernel* phases of cyclus's cardinal function. Thus, by extent, - Tick - Tock @@ -94,14 +96,14 @@ filtering options that consider deregistering an agent's Tocks/Decisions when th Implementation =============================== -Material requests, Build, and Decomissioin event registration will be handled by individual agents. |Cyclus| already creates a preconditioned timeline -for discrete-build and decomission events. An additional ``EventRequest()`` member funcition for all |cycamore| archetypes will check a facility's inventory. +Material requests, Build, and Decomissioin event registration will be handled by individual agents. Cyclus already creates a preconditioned timeline +for discrete-build and decomission events. An additional ``EventRequest()`` member funcition for all cycamore archetypes will check a facility's inventory. 1. If inventory not at capacity, agent will register for the (+1) next immediate time step to attempt another request. 2. If inventory at capacity, agent will register its next request event for a fixed ``+ cycle_length`` time from the current event. These material request events will be registered within Context in a dynamic dictionary that contains the event's timestamp and a list of ``Trader`` objects. To ensure that all -facility agents' ``EventRequest()`` functions are checked regularly, A look-ahead function will be added to |cyclus's| cardinal phase suite after the decomissioning phase. +facility agents' ``EventRequest()`` functions are checked regularly, A look-ahead function will be added to cyclus's cardinal phase suite after the decomissioning phase. .. code-block:: c++ DoBuild(); @@ -120,7 +122,7 @@ The simulation will be terminated fully when ``DoLookAhead()`` registers no new Backwards Compatibility ======================== -These changes will not be backwards compatible with |cyclus| v1.6.0 and may require a new release. An optional simulation parameter could be introduced to switch this treatment on and off +These changes will not be backwards compatible with cyclus v1.6.0 and may require a new release. An optional simulation parameter could be introduced to switch this treatment on and off such that the original time implemenation can be used. From 194ad4e8899e67fec9e4426ab104e1ab724ebdd9 Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Fri, 20 Feb 2026 09:46:42 -0800 Subject: [PATCH 7/8] typos --- source/cep/cep31.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index e6ab2c65..362d4f0c 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -3,12 +3,12 @@ CEP 31 - Agent Registered Discrete Event Timing :CEP: 31 :Title: Agent Registered Discrete Event Timing -:Last-Modified: 2026-02-19 +:Last-Modified: 2026-02-20 :Author: Meghan Krieg :BDFP: Madicken Munk/Paul Wilson :Status: Draft :Type: Standards Track -:Created: 2026-02-20 +:Created: 2026-02-19 :Cyclus-Version: 1.6.0 Background @@ -46,12 +46,13 @@ where no actions are registered. For example, an agent may schedule a build-even Then, the timeline for a 10 month simulation will proceed as follows .. class:: center -START 3 (build) -- 5 (trade) -- 7 (decom) END + + **START 3 (build) -- 5 (trade) -- 7 (decom) END** as opposed to the current implementation .. class:: center -START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END + **START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END** In cyclus, discrete even timing can be implemented by allowing agents to internally check their inventory and status to register themselves for DRE participation, Build, or Decomission events. In instances @@ -114,7 +115,7 @@ facility agents' ``EventRequest()`` functions are checked regularly, A look-ahea DoDecom(); DoLookAhead(); -The cardinal phase suite will maintain its current ordering for the reasons described in ---. Each of the 6 phases will be checked during each event (as opposed to each time step) but the phase will +The cardinal phase suite will maintain its current ordering for the reasons described in CEP 20. Each of the 6 phases will be checked during each event (as opposed to each time step) but the phase will only be triggered and completed if it has participants registered. Only the newly introduced ``DoLookAhead()`` that checks each agents ``EventRequest()`` will be executed for all agents each event. The simulation will be terminated fully when ``DoLookAhead()`` registers no new events and the simulation has completed the last event registered. From 1bb20a27e11337d08e4f45bb53051c81967e3634 Mon Sep 17 00:00:00 2001 From: meg-krieg Date: Fri, 20 Feb 2026 09:51:00 -0800 Subject: [PATCH 8/8] formatting --- source/cep/cep31.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/cep/cep31.rst b/source/cep/cep31.rst index 362d4f0c..60752584 100644 --- a/source/cep/cep31.rst +++ b/source/cep/cep31.rst @@ -45,14 +45,11 @@ within the simulation duration. The simulation progresses from scheduled event t where no actions are registered. For example, an agent may schedule a build-event at timestamp 5, a trade event at timestamp 7, and a decomission event at timestamp 10. Then, the timeline for a 10 month simulation will proceed as follows -.. class:: center - - **START 3 (build) -- 5 (trade) -- 7 (decom) END** +START 3 (build) -- 5 (trade) -- 7 (decom) END as opposed to the current implementation -.. class:: center - **START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END** +START 0 -- 1 -- 2 -- 3 (build) -- 4 -- 5 (trade) -- 6 -- 7 (decom) -- 8 -- 9 -- 10 END In cyclus, discrete even timing can be implemented by allowing agents to internally check their inventory and status to register themselves for DRE participation, Build, or Decomission events. In instances