CEP 2 - Separation of Concerns in the Cyclus Ecosystem¶
- CEP:
2
- Title:
Separation of Concerns in the Cyclus Ecosystem, or Where Do I Put My Code?
- Last-Modified:
2017-09-01
- Author:
Anthony Scopatz, Matthew Gidden
- Status:
Accepted
- Type:
Process
- Created:
2013-08-05
Abstract¶
The purpose of this CEP is to clearly delineate the purpose – technical and cultural – of the various projects which make up the Cyclus ecosystem. Projects, for purposes here, are unique entities which have independent lifetimes and central concerns. Many projects may try to tackle the same concern but no single project may tackle more than one concern. Concerns, like projects, may be dependent upon one another.
The central concerns in the Cyclus ecosystem are dynamic resource exchange simulation (DRES), domain models (DM), analysis & visualization (A&V), and simulation orchestration (ORC).
Concerns¶
A rich fuel cycle simulator solution has four primary organizational pieces that must have robust implementations. These pieces are a mechanism for solving for resource exchange in the fuel cycle, relevant and interesting models for the domains of interest (physics, economics, policy, etc.), a programmatic method for parsing, slicing, aggregating, and displaying simulation results, and a mechanism for executing and collecting many simulations. As an effectively designed suite of software, these concerns should be completely separated from one another and interact only through well-defined interfaces [1]. This independence allows both users and developers to reason about each concern without needing to consider upstream effects. Coupled with a stable interface or API, this independence also allows users and developers to ignore downstream effects in most cases.
The domain model concern is dependent only on the resource exchange concern. However, the analysis & visualization concern is directly dependent on both the resource exchange and the domain model concerns. These relationships may be seen in Figure 1.
Figure 1: Dependencies Between Concerns¶
Dynamic Resource Exchange Simulation¶
The dynamic resource exchange simulation concern is the basis for all other fuel cycle concerns. This dictates and manages how resources flow through a system and the time paradigm used to model the system. A number of possible representations of system elements exist. Two main options stand out: 1) individual-based models in which every actor receives its own instance, and 2) fleet-based models where like actors are grouped together and act identically. Resource exchange may be implemented using a strict agent-based modeling [2] approach or strict system dynamics methods [3]. However, these two paradigms are not restrictive and implementations may pull from a variety of algorithms as needed.
Furthermore, the choice of how to represent time evolution may fall into one of the following categories:
Equilibrium - initial transients are ignored or discarded in favor of a steady state solution.
Quasi-static - initial transients are computed but natural time (sec, min, etc) are replaced with an easier to compute number of passes through a given actor.
Discrete time - natural time is implemented but discretized to some minimum and constant dt.
Adaptive time - natural time is implemented and discretized, but the value of dt may change from time step to time step, allowing for finer resolution only when needed.
Continuous time - natural time is implemented as a continuous variable.
It is important to note that this concern is a solely mathematical endeavor and should not implement any domain-specific calculations. However, the implementation may be domain-aware in that it may know about certain sub-type specializations. For example, materials and U.S. Dollars are both sub-types of resources. Still, the dynamic resource exchange simulation concern is not allowed to discriminate between any of these specializations nor perform domain-specific computations (such as transmuting a material or pricing a derivative).
This concern is responsible for housing general archetypes that allow for general, dynamic simulation of supply chain networks in a resource-neutral manner. Supply chain network models require, at minimum, three types of entities (i.e., nodes) [BJS11]:
Sources (supply nodes)
Storage (transshipment nodes)
Sinks (demand nodes)
In addition to enabling such basic simulations, the dynamic resource exchange simulation concern is also responsible for all optimizations of the fuel cycle. This includes optimizing resource exchange between multiple actors as well as finding the initial conditions which optimize a value function subject to some constraints.
Domain Models¶
The purpose of the domain models concern is to provide interesting, accurate, and relevant models of various aspects of the fuel cycle. These aspects are often the technical meat of the fuel cycle analysis. However, they may be mathematically separated from resource exchange. This concern ensures that those mathematical separations remain distinct in the software. There are a number of domain models which are pertinent to fuel cycle calculations:
Physics
Chemistry
Health Physics
Economics
Public Policy
and more!
The implementation of specific domain computations should rely on the system dynamics for all systematic flow and timing needs. The implementation of the domain calculations should be completely separated from the system dynamics concern. This establishes a clean interface between these two concerns.
For example, take an enrichment facility which is asked to compute product and tails enrichments. In the initialization of this calculation, the dynamic resource exchange simulation concern hands off the simulation time (t), the time delta (dt), and the initial feed material to the underlying physics model. The physics model then computes the desired outputs without further interaction with the resource exchange model. Lastly, the outputs are returned to the DRES model.
Analysis & Visualization¶
The purpose of the analysis & visualization concern is to supply aggregation and introspection into the simulation outputs. The analysis may take place at both high and low levels, common aggregations should be easy to perform, and static and interactive visualization should be provided as a mechanism for easy human consumption. All post-processing of simulation data falls under this concern.
The analysis & visualization concern is dependent directly on both the dynamic resource exchange simulation concern and the domain models concern. This is because meaningful inspection of simulation data requires parameters from both concerns. Note that these dependencies are independent. The analysis & visualization tools must handle the case where only DRES models are used. However, if domain models are used and the analysis & visualization is aware of these domain models, all DRES parameters are guaranteed to also be present.
Simulation Orchestration¶
Simulation campaigns often involve executing multiple instances of the DRE and associated analysis and visualization. This may be with the purpose of,
performing a sensitivity study,
running a parameter sweep,
sampling from a large option space, or
creating a training set for machine learning models.
This execution and analysis is either managed manually or automatically, but it is always managed. Running, analyzing, visualizing, and generating many Cyclus input files is termed here “orchestration.” This includes provisioning compute resources where these tasks are executed. Data management also falls under the purview of simulation orchestration.
Simulation orchestration provides a feedback loop for the Cyclus ecosystem. It both drives the DRE simulator and incorporates the results of previous simulations.
The Cyclus Ecosystem¶
While many fuel cycle simulators may choose to implement all of the above concerns in a single project, each concern in the Cyclus ecosystem is implemented in its own project. Many projects may satisfy the needs of a concern. However, no project may try to address multiple concerns. This provides a clear guideline for which projects should accept which kinds of code.
If for some reason ambiguities exist, first attempt to refactor the code at hand with these concerns in mind. If this fails because of a fundamental ambiguity or mixing of multiple concerns, place the code with the most dependent concern. For example, if it is not clear if a class belongs with domain models or with the resource exchange put it with the domain models to be safe.
The Cyclus development team currently supports projects for these concerns:
Cyclus - Dynamic Resource Exchange Simulation (individual actors, discrete time, canonical supply chain entities)
Cycamore - Domain Models
Cymetric - Analysis & Visualization
Cyclist - Analysis & Visualization (historical)
Rickshaw - Simulation orchestration
The dependency graph for these projects is similar to the graph of the concerns. Figure 2 displays this graph along with other projects which implement these concerns.
Figure 2: Dependencies Between Projects is Cyclus Ecosystem.¶
Toolkits¶
In any real system, there is glue code which holds the projects together in a cohesive manner. A collection of such utilities is called a toolkit. While toolkits are critically important to well functioning software their components are united only in that “should be useful.” There need not be underlying concept tying them together. For this reason, toolkits are not a top-level concern on par with resource exchange, domain models, and analysis & visualization.
Instead, each project may have its own toolkit which contains utilities that corresponds most closely with its concern. The toolkit provides a layer on top of the concern implementation. Thus the toolkit will be aware of other parts of the project but the concern implementation should not call into elements from the toolkit.
For example, resources are part of the primary concern of Cyclus. Thus a ResourceBuffer class would be part of the Cyclus toolkit. This is because resource exchange can be implemented without a ResourceBuffer but such a class is useful to provide to domain model developers. Furthermore, the buffer applies to all resources is not specific to any domain. Thus this class should be included next to the resource exchange implementation.
Summary¶
Many other ecosystems and projects model the fuel cycle and make their own choices about how to separate – or not – the concerns of resource exchange, domain models, and analysis and visualization. The Cyclus ecosystem places all concerns in separate projects. This allows a high degree of modularity between software and developers. Such an ecosystem enables experts to contribute their specific knowledge base in a way that is independent from other parts of the ecosystem while simultaneously integrating well with the rest of the ecosystem. Finally, this document provides instructions on where to implement tasks based on the task’s primary concern.
Document History¶
This document is released under the CC-BY 3.0 license.
References and Footnotes¶
Mokhtar S Bazaraa, John J Jarvis, and Hanif D Sherali. Linear programming and network flows. John Wiley & Sons, 2011.
