cep-30 document rewrite

Author: dean-krueger

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 <[email protected]>
 :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<std::string, double>` 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.