From 4daeb4f1e6d6aaad358bb68d295d9c7d417b033a Mon Sep 17 00:00:00 2001 From: Dean Krueger Date: Sun, 29 Dec 2024 21:40:05 -0600 Subject: [PATCH 01/12] Added first draft of CEP 30 to website --- source/cep/cep30.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 source/cep/cep30.rst diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst new file mode 100644 index 00000000..537bbe94 --- /dev/null +++ b/source/cep/cep30.rst @@ -0,0 +1,78 @@ +CEP 30 - Improvements to Cyclus Supply-Demand Framework +********************************************************* + +:CEP: 30 +:Title: Improvements to Cyclus Supply-Demand Framework +:Last-Modified: 2024-12-27 +:Author: Dean Krueger +:BDFP: Paul Wilson +:Status: Draft +:Type: Standards Track +:Created: 2024-11-26 +:Cyclus-Version: 1.6.0 + + +Abstract +======== + +The DRE of the current version of CYCLUS handles the cost of materials being traded in a +way which was always intended to be expanded upon as discussed in the Supply-Demand +Framework section of CEP 18. This CEP references moving the Supply-Demand from being +requester based to being supplier based, with more considerations for economics. As a part +of moving the DRE in that direction, it is necessary to add economic-based elements to +the definitions of the Region, Institution, and Facility in such a way as to allow them +to interact with each other economically. The proposal for doing so is to add sub-classes +to each which will act as a method of communicating economic information between layers +of the simulation. + +Copyright: +============================== + +CEP 30 will be placed in the public domain as required by CEP 1. + +Specification: +============================ + +The new feature being proposed is a subclass for each of the Region, Institution, and +Facility classes which will allow the communication of economic data between each layer +of the CYCLUS simulation. The main feature of the subclass will be a hash table +(enabled by std::unordered_map) which contains pairs of keys (std::string) and values +(doubles), as well as functions to set and get elements in the table. + +Motivation: +================== + +The major motivation for this new feature is that currently when a Facility tries to access +information about its Institution, it can only reliably use the public API of the Institution +base class. That is, it is dangerous to try to access something that is only in the public +API of a derived Institution archetype because it may not always be there. Because of the +interdependence of imagined economic functionality on the Facility-Institution-Region +relationship (a facility’s cost may be impacted by its own capital cost, as well as its +parent institution’s minimum acceptable rate of return and the regional tax rate, for +instance), the ability of a facility to access information about its parent Agents is +crucial. + +Rationale: +=========================== + +It was decided to make the overall feature a subclass is to keep it in line with the class-subclass +structure of other CYCLUS functionality, such as the Facility Institution Region - Agent structure. +The reasons for choosing a hash table over another data structure are that they allow quick and +easy expansion both by developers and within the simulation itself, as well as search, insert, and +delete operations being ostensibly O(1). + +During the public vetting stage of CEP 30’s lifecycle two alternative ideas for implementing this +behavior were proposed. The first was to use the code injection functionality of cycpp files to +add economic information to archetypes themselves at the beginning of simulations. This was tested, +but it was discovered that there were problems accessing the information of parent agents, and it +was determined that this approach would be some combination of too cumbersome and less certain to +work. The second idea was to implement some sort of registry, similar to how Microsoft Windows +(and other operating systems) handle some of their internal operations, but this was deemed to be +too much of a bloat hazard, as registries can become very complicated very quickly. + +Backwards Compatibility: +=========================== + +Since this feature is proposed as a subclass of each of the three agent subclasses, it will be +optional to use, and therefore entirely possible to completely ignore it. This means it should +require no work to ensure backwards compatibility with older versions of CYCLUS. From e6efa4810c8b033d9db18094448362c61bf33fbd Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:20:12 -0600 Subject: [PATCH 02/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 537bbe94..b77ff523 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -17,11 +17,13 @@ Abstract The DRE of the current version of CYCLUS handles the cost of materials being traded in a way which was always intended to be expanded upon as discussed in the Supply-Demand -Framework section of CEP 18. This CEP references moving the Supply-Demand from being -requester based to being supplier based, with more considerations for economics. As a part -of moving the DRE in that direction, it is necessary to add economic-based elements to +Framework section of [CEP 18](https://fuelcycle.org/cep/cep18.html). In particular, that CEP +suggests that the introduction of economic concepts could allow the supplier to have more +influence over the preferences of particular trading paths. As a part +of moving the DRE in that direction, it is necessary to add economic parameters to the definitions of the Region, Institution, and Facility in such a way as to allow them -to interact with each other economically. The proposal for doing so is to add sub-classes +to interact with each other to combine these parameters in meaningful ways. The proposal +for doing so is to add sub-classes to each which will act as a method of communicating economic information between layers of the simulation. From 35dd45249a9599b1f270bacf141ee720011e5c14 Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:20:26 -0600 Subject: [PATCH 03/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index b77ff523..dbe39abd 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -36,8 +36,8 @@ Specification: ============================ The new feature being proposed is a subclass for each of the Region, Institution, and -Facility classes which will allow the communication of economic data between each layer -of the CYCLUS simulation. The main feature of the subclass will be a hash table +Facility classes which will allow the communication of economic/financial data between each layer +of the CYCLUS Region-Institution-Facility hierarchy. The main feature of the subclass will be a hash table (enabled by std::unordered_map) which contains pairs of keys (std::string) and values (doubles), as well as functions to set and get elements in the table. From 9906da623426ec1d6cc40e7b76dc50b0171857e2 Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:20:58 -0600 Subject: [PATCH 04/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index dbe39abd..5bd282ee 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -47,7 +47,11 @@ Motivation: The major motivation for this new feature is that currently when a Facility tries to access information about its Institution, it can only reliably use the public API of the Institution base class. That is, it is dangerous to try to access something that is only in the public -API of a derived Institution archetype because it may not always be there. Because of the +API of a derived Institution archetype because it may not always be there. +This eliminates the use of the optional Toolkit to introduce economic/financial parameters +into agents that are required to interact for those parameters since C++ doesn't provide +a way to interrogate the API of an agent. +Because of the interdependence of imagined economic functionality on the Facility-Institution-Region relationship (a facility’s cost may be impacted by its own capital cost, as well as its parent institution’s minimum acceptable rate of return and the regional tax rate, for From 0d579b7c02cd075166595a9a216e4de401ddd105 Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:21:10 -0600 Subject: [PATCH 05/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 5bd282ee..76b01682 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -52,7 +52,7 @@ This eliminates the use of the optional Toolkit to introduce economic/financial into agents that are required to interact for those parameters since C++ doesn't provide a way to interrogate the API of an agent. Because of the -interdependence of imagined economic functionality on the Facility-Institution-Region +interdependence of imagined economic functionality on the Region-Institution-Facility relationship (a facility’s cost may be impacted by its own capital cost, as well as its parent institution’s minimum acceptable rate of return and the regional tax rate, for instance), the ability of a facility to access information about its parent Agents is From 9fc71a66f8af116d0f44c8bc9a1f1ed528f894ea Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:21:23 -0600 Subject: [PATCH 06/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 76b01682..ee424c1d 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -61,7 +61,7 @@ crucial. Rationale: =========================== -It was decided to make the overall feature a subclass is to keep it in line with the class-subclass +Implementing the overall feature as a subclass keeps it in line with the class-subclass structure of other CYCLUS functionality, such as the Facility Institution Region - Agent structure. The reasons for choosing a hash table over another data structure are that they allow quick and easy expansion both by developers and within the simulation itself, as well as search, insert, and From 1cba85c1e36c34c17ff090782a7bcf42fd863608 Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:21:40 -0600 Subject: [PATCH 07/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index ee424c1d..63bc33fc 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -62,7 +62,7 @@ Rationale: =========================== Implementing the overall feature as a subclass keeps it in line with the class-subclass -structure of other CYCLUS functionality, such as the Facility Institution Region - Agent structure. +structure of other CYCLUS functionality, such as the `TimeAgent` or `Trader` features that are inherited this way. The reasons for choosing a hash table over another data structure are that they allow quick and easy expansion both by developers and within the simulation itself, as well as search, insert, and delete operations being ostensibly O(1). From 0dc341f78d0442393f4c736a6cac48bd32c0cb82 Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Thu, 6 Feb 2025 10:21:58 -0600 Subject: [PATCH 08/12] Update source/cep/cep30.rst Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 63bc33fc..5615034a 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -69,7 +69,7 @@ delete operations being ostensibly O(1). During the public vetting stage of CEP 30’s lifecycle two alternative ideas for implementing this behavior were proposed. The first was to use the code injection functionality of cycpp files to -add economic information to archetypes themselves at the beginning of simulations. This was tested, +add economic information as an optional Toolkit feature to archetypes themselves at the beginning of simulations. This was tested, but it was discovered that there were problems accessing the information of parent agents, and it was determined that this approach would be some combination of too cumbersome and less certain to work. The second idea was to implement some sort of registry, similar to how Microsoft Windows From 997b0eb4495a1b9d32adc32f93b0b7b5fdbd5b22 Mon Sep 17 00:00:00 2001 From: Dean Krueger Date: Thu, 6 Feb 2025 10:30:26 -0600 Subject: [PATCH 09/12] Changed title to be more focused --- source/cep/cep30.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 5615034a..f6554e2e 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -1,8 +1,8 @@ -CEP 30 - Improvements to Cyclus Supply-Demand Framework +CEP 30 - Framework for Financial Parameter Exchange in the CYCLUS R-I-F Hierarchy ********************************************************* :CEP: 30 -:Title: Improvements to Cyclus Supply-Demand Framework +:Title: Framework for Financial Parameter Exchange in the CYCLUS R-I-F Hierarchy :Last-Modified: 2024-12-27 :Author: Dean Krueger :BDFP: Paul Wilson From a24c543790f1b0a1586db8afd58491cb658a0478 Mon Sep 17 00:00:00 2001 From: Dean Krueger Date: Thu, 6 Feb 2025 10:34:25 -0600 Subject: [PATCH 10/12] removed mention of Windows, and added bit about future use of toolkit --- source/cep/cep30.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index f6554e2e..90517f19 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -69,12 +69,13 @@ delete operations being ostensibly O(1). During the public vetting stage of CEP 30’s lifecycle two alternative ideas for implementing this behavior were proposed. The first was to use the code injection functionality of cycpp files to -add economic information as an optional Toolkit feature to archetypes themselves at the beginning of simulations. This was tested, -but it was discovered that there were problems accessing the information of parent agents, and it -was determined that this approach would be some combination of too cumbersome and less certain to -work. The second idea was to implement some sort of registry, similar to how Microsoft Windows -(and other operating systems) handle some of their internal operations, but this was deemed to be -too much of a bloat hazard, as registries can become very complicated very quickly. +add economic information as an optional Toolkit feature to archetypes themselves at the beginning +of simulations. This was tested, but it was discovered that there were problems accessing the +information of parent agents, and it was determined that this approach would be some combination +of too cumbersome and less certain to work. Eventually, the toolkit approach will likely be used +in conjunction with the features added by this CEP. The second idea was to implement some sort of +registry, but this was deemed to be too much of a bloat hazard, as registries can become very +complicated very quickly. Backwards Compatibility: =========================== From 8bf769584635c3968b452dbfac8a3c7a5ff1f831 Mon Sep 17 00:00:00 2001 From: Dean Krueger Date: Tue, 8 Jul 2025 13:59:58 -0500 Subject: [PATCH 11/12] cep-30 document rewrite --- source/cep/cep30.rst | 48 ++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 90517f19..34467250 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -1,8 +1,8 @@ -CEP 30 - Framework for Financial Parameter Exchange in the CYCLUS R-I-F Hierarchy +CEP 30 - Framework for Parameter Exchange in the CYCLUS R-I-F Hierarchy ********************************************************* :CEP: 30 -:Title: Framework for Financial Parameter Exchange in the CYCLUS R-I-F Hierarchy +:Title: Framework for Parameter Exchange in the CYCLUS R-I-F Hierarchy :Last-Modified: 2024-12-27 :Author: Dean Krueger :BDFP: Paul Wilson @@ -22,10 +22,11 @@ suggests that the introduction of economic concepts could allow the supplier to influence over the preferences of particular trading paths. As a part of moving the DRE in that direction, it is necessary to add economic parameters to the definitions of the Region, Institution, and Facility in such a way as to allow them -to interact with each other to combine these parameters in meaningful ways. The proposal -for doing so is to add sub-classes -to each which will act as a method of communicating economic information between layers -of the simulation. +to interact with each other to combine these parameters in meaningful ways. However, because +of the way that these financial parameters are tied intrisically to different parts of the +Region-Institution-Facility (RIF) hierarchy, it will be necessary to introduce some mechanic +by which those different layers of the hierarchy communicate their parameters to each other +so that meaninful financial functions can be implemented. Copyright: ============================== @@ -35,11 +36,11 @@ CEP 30 will be placed in the public domain as required by CEP 1. Specification: ============================ -The new feature being proposed is a subclass for each of the Region, Institution, and -Facility classes which will allow the communication of economic/financial data between each layer -of the CYCLUS Region-Institution-Facility hierarchy. The main feature of the subclass will be a hash table -(enabled by std::unordered_map) which contains pairs of keys (std::string) and values -(doubles), as well as functions to set and get elements in the table. +The new feature being proposed is a parent class for `Agent`, called `EconomicEntity`, which will +add a common set of functions for accessing an `std::unordered_map` called +`financial_data_`. This map will be private, and only accessible through getter and setter functions. +Additionally, the `EconomicEntity` class will include some common financial operation functions +such as a present value function, a future value function, etc. Motivation: ================== @@ -52,20 +53,18 @@ This eliminates the use of the optional Toolkit to introduce economic/financial into agents that are required to interact for those parameters since C++ doesn't provide a way to interrogate the API of an agent. Because of the -interdependence of imagined economic functionality on the Region-Institution-Facility -relationship (a facility’s cost may be impacted by its own capital cost, as well as its -parent institution’s minimum acceptable rate of return and the regional tax rate, for -instance), the ability of a facility to access information about its parent Agents is -crucial. +interdependence of imagined economic functionality on the RIF relationship (a facility’s +cost may be impacted by its own capital cost, as well as its parent institution’s minimum +acceptable rate of return and the regional tax rate, for instance), the ability of a facility +to access information about its parent Agents is crucial. Rationale: =========================== -Implementing the overall feature as a subclass keeps it in line with the class-subclass -structure of other CYCLUS functionality, such as the `TimeAgent` or `Trader` features that are inherited this way. -The reasons for choosing a hash table over another data structure are that they allow quick and -easy expansion both by developers and within the simulation itself, as well as search, insert, and -delete operations being ostensibly O(1). +Implementing the overall feature as a supercklass keeps it in line with the class-subclass +structure of other CYCLUS functionality. The reasons for choosing a hash table over another +data structure are that they allow quick and easy expansion both by developers and within +the simulation itself, as well as search, insert, and delete operations being ostensibly O(1). During the public vetting stage of CEP 30’s lifecycle two alternative ideas for implementing this behavior were proposed. The first was to use the code injection functionality of cycpp files to @@ -80,6 +79,7 @@ complicated very quickly. Backwards Compatibility: =========================== -Since this feature is proposed as a subclass of each of the three agent subclasses, it will be -optional to use, and therefore entirely possible to completely ignore it. This means it should -require no work to ensure backwards compatibility with older versions of CYCLUS. +Since this feature is proposed as a superclass of each of the `Agent` class, it will be +a fundamental change to Cyclus. However, use of this feature will be completely optional, since +all it does is add addtional information/functionality to Cyclus, and doesn't change any +preexisting code. From e28ffbdfadee90fb3738724fcd6fb6ae580fca4b Mon Sep 17 00:00:00 2001 From: Dean Krueger <74223179+dean-krueger@users.noreply.github.com> Date: Tue, 8 Jul 2025 16:26:55 -0500 Subject: [PATCH 12/12] Update "Last Modified" date Co-authored-by: Paul Wilson --- source/cep/cep30.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/cep/cep30.rst b/source/cep/cep30.rst index 34467250..2613a547 100644 --- a/source/cep/cep30.rst +++ b/source/cep/cep30.rst @@ -3,7 +3,7 @@ CEP 30 - Framework for Parameter Exchange in the CYCLUS R-I-F Hierarchy :CEP: 30 :Title: Framework for Parameter Exchange in the CYCLUS R-I-F Hierarchy -:Last-Modified: 2024-12-27 +:Last-Modified: 2025-07-08 :Author: Dean Krueger :BDFP: Paul Wilson :Status: Draft