Skip to content

Commit

Permalink
Merge pull request cyclus#370 from bennibbelink/resource-buff
Browse files Browse the repository at this point in the history 
Deprecate `ResourceBuff`
  • Loading branch information
@gonuke
gonuke authored May 20, 2024
2 parents a33ddfd + 1197675 commit 50b43a6
Show file tree
Hide file tree
Showing 3 changed files with 117 additions and 175 deletions.
2 changes: 1 addition & 1 deletion docker/Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@ FROM ghcr.io/cyclus/cymetric_22.04_apt/cymetric:latest

RUN apt-get update
RUN apt-get install -y --force-yes wget python3-pip
RUN python -m pip install sphinx sphinxcontrib-bibtex cloud-sptheme
RUN python3 -m pip install sphinx sphinxcontrib-bibtex cloud-sptheme

289 changes: 116 additions & 173 deletions source/arche/toolkit.rst
View file
Original file line number Diff line number Diff line change
@@ -1,173 +1,116 @@
.. _toolkit:

The (Experimental) Cyclus Toolkit
=================================
Currently in an experimental state, the |cyclus| toolkit aims to provide
functionality relevant to a variety of :term:`archetypes <archetype>` that do
not belong strictly in the :term:`cyclus kernel`.

ResourceBuff
++++++++++++
.. warning::

ResourceBuff will soon be deprecated in favor of ``ResBuf``.

The ``cyclus::toolkit::ResourceBuff`` (C++) or ``cyclus.typesystem.ResourceBuff`` (Python)
class provides provides a canonical
methodology for dealing with collections of ``Resources``.
:term:`Archetypes <archetype>` in both |cyclus| and Cycamore make use of this
class. ``ResourceBuffs`` are usually used as member variables of
archetypes. The |Cyclus| preprocessor (C++) or |Cyclus| agents (Python) have special
handling for ``ResourceBuff``
as it can generate all needed code for proper persistence and intiialization
of the buffer. For this to work, you must annotate the buffer member variable
with a Cyclus pre-processor :ref:`pragma <pragma-cyclus-var>` (C++) or have a
special ``ResourceBuffInv`` class attribute (Python) in one of the
following ways:

**C++:**

.. code-block:: c++

// Option 1: minimum required annotation
#pragma cyclus var {}
cyclus::toolkit::ResourceBuff mybuf;

// Option 2: you can set a specify buffer capacity
#pragma cyclus var {'capacity': 245.6}
cyclus::toolkit::ResourceBuff mybuf;

// Option 3: you can reference another annotated member variable's value
// as the capacity
#pragma cyclus var {}
double buf_cap;
#pragma cyclus var {'capacity': 'buf_cap'}
cyclus::toolkit::ResourceBuff mybuf;

**Python:**

.. code-block:: python
from cyclus.agents import Facility
import cyclus.typesystem as ts
class MyFacility(Facility):
# Option 1: minimum required class attribute
mybuf = ts.ResourceBuffInv()
# Option 2: you can set a specify buffer capacity
mybuf = ts.ResourceBuffInv(capacity=245.6)
# Option 3: you can reference another annotated member variable's value
# as the capacity
buf_cap = ts.Double()
mybuf = ts.ResourceBuffInv(capacity='buf_cap')
You can read the `ResourceBuff API documentation
<http://fuelcycle.org/cyclus/api/classcyclus_1_1toolkit_1_1ResourceBuff.html>`_ for
more details on how to use the buffer.

ResBuf
++++++++++++
The ``cyclus::toolkit::ResBuf`` (C++) or ``cyclus.typesystem.ResBuf`` (Python) class
provides provides a canonical
methodology for dealing with collections of Resources. ``ResBufs``
are usually used as member variables of archetypes. The Cyclus preprocessor
has special handling for ``ResBuf`` as it can generate all needed code
for proper persistence and intiialization of the buffer. For this to work,
you must annotate the buffer member variable with a Cyclus pre-processor
:ref:`pragma <pragma-cyclus-var>` (C++) or set a class attribute (Python)
in one of the following ways:

**C++:**

.. code-block:: c++

// Option 1: minimum required annotation
#pragma cyclus var {}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

// Option 2: you can set a specify buffer capacity
#pragma cyclus var {'capacity': 245.6}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

// Option 3: you can reference another annotated member variable's value
// as the capacity
#pragma cyclus var {}
double buf_cap;
#pragma cyclus var {'capacity': 'buf_cap'}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

**Python:**

.. code-block:: python
from cyclus.agents import Facility
import cyclus.typesystem as ts
class MyFacility(Facility):
# Option 1: minimum required annotation
mybuf = ts.ResBufMaterialInv()
# Option 2: you can set a specify buffer capacity
mybuf = ts.ResBufMaterialInv(capacity=245.6)
# Option 3: you can reference another annotated member variable's value
# as the capacity
buf_cap = ts.Double()
mybuf = ts.ResBufMaterialInv(capacity='buf_cap')
You can read the `ResBuf API documentation
<http://fuelcycle.org/cyclus/api/classcyclus_1_1toolkit_1_1ResBuf.html>`_ for
more details on how to use the buffer.

MatQuery [C++]
++++++++++++++
The ``cyclus::toolkit::MatQuery`` class provides some easy-to-use functions that
interrogate the ``cyclus::Material`` object. For example, one can query the mass
or number of moles of a given nuclide.

Enrichment [C++]
++++++++++++++++
A number of functions are provided in ``toolkit/enrichment.h`` that assist in
enrichment-related calculations. Some highlights include a representation of
uranium assays in ``cyclus::toolkit::Assays``, as well as functions to calculate
feed, tails, and SWU quantity requirements.

Commodity Recipe Context [C++]
+++++++++++++++++++++++++++++++
The ``cyclus::toolkit::CommodityRecipeContext`` class provides a mapping between
commodities and recipes that can be updated as a simulation progresses.

Symbolic Functions [C++]
++++++++++++++++++++++++
The ``cyclus::toolkit::SymbolicFunction`` class and its derivatives provide an
object-oriented hierarchy to represent symbolic functions. Factory methods are
provided by the ``cyclus::toolkit::SymbFunctionFactory`` class.

Agent Managed Classes [C++]
+++++++++++++++++++++++++++
There are a number of interfaces provided in the |cyclus| toolkit that can be
used as either as `mixins <http://en.wikipedia.org/wiki/Mixin>`_ or as
composable, agent-managed state variables:

* ``cyclus::toolkit::Builder``: an interface for adding information about agents
that can be built by the manager

* ``cyclus::toolkit::BuildingManager``: an interface for making build decisions
based on supply, demand, and agents that can be built

* ``cyclus::toolkit::CommodityProducer``: an interface for adding information
about commodities that can be produced by the manager

* ``cyclus::toolkit::CommodityProducerManager``: an interface that allows an
agent to query a collection of ``cyclus::toolkit::CommodityProducers``

* ``cyclus::toolkit::SupplyDemandManager``: an interface for querying the supply
and demand on commodities

Geographic Informasion System (GIS) Class [C++]
+++++++++++++++++++++++++++++++++++++++++++++++
The ``cyclus::toolkit::GIS`` class provide an option to add geographic coordinates
of its friend classes. Haversine distance calculations between two facilities or
agents with GIS coordinates can be performed as well.
.. _toolkit:

The (Experimental) Cyclus Toolkit
=================================
Currently in an experimental state, the |cyclus| toolkit aims to provide
functionality relevant to a variety of :term:`archetypes <archetype>` that do
not belong strictly in the :term:`cyclus kernel`.

ResBuf
++++++++++++
The ``cyclus::toolkit::ResBuf`` (C++) or ``cyclus.typesystem.ResBuf`` (Python) class
provides provides a canonical
methodology for dealing with collections of Resources. ``ResBufs``
are usually used as member variables of archetypes. The Cyclus preprocessor
has special handling for ``ResBuf`` as it can generate all needed code
for proper persistence and intiialization of the buffer. For this to work,
you must annotate the buffer member variable with a Cyclus pre-processor
:ref:`pragma <pragma-cyclus-var>` (C++) or set a class attribute (Python)
in one of the following ways:

.. note::

``ResourceBuff`` has been deprecated in favor of ``ResBuf``.

**C++:**

.. code-block:: c++

// Option 1: minimum required annotation
#pragma cyclus var {}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

// Option 2: you can set a specify buffer capacity
#pragma cyclus var {'capacity': 245.6}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

// Option 3: you can reference another annotated member variable's value
// as the capacity
#pragma cyclus var {}
double buf_cap;
#pragma cyclus var {'capacity': 'buf_cap'}
cyclus::toolkit::ResBuf<cyclus::Material> mybuf;

**Python:**

.. code-block:: python
from cyclus.agents import Facility
import cyclus.typesystem as ts
class MyFacility(Facility):
# Option 1: minimum required annotation
mybuf = ts.ResBufMaterialInv()
# Option 2: you can set a specify buffer capacity
mybuf = ts.ResBufMaterialInv(capacity=245.6)
# Option 3: you can reference another annotated member variable's value
# as the capacity
buf_cap = ts.Double()
mybuf = ts.ResBufMaterialInv(capacity='buf_cap')
You can read the `ResBuf API documentation
<http://fuelcycle.org/cyclus/api/classcyclus_1_1toolkit_1_1ResBuf.html>`_ for
more details on how to use the buffer.

MatQuery [C++]
++++++++++++++
The ``cyclus::toolkit::MatQuery`` class provides some easy-to-use functions that
interrogate the ``cyclus::Material`` object. For example, one can query the mass
or number of moles of a given nuclide.

Enrichment [C++]
++++++++++++++++
A number of functions are provided in ``toolkit/enrichment.h`` that assist in
enrichment-related calculations. Some highlights include a representation of
uranium assays in ``cyclus::toolkit::Assays``, as well as functions to calculate
feed, tails, and SWU quantity requirements.

Commodity Recipe Context [C++]
+++++++++++++++++++++++++++++++
The ``cyclus::toolkit::CommodityRecipeContext`` class provides a mapping between
commodities and recipes that can be updated as a simulation progresses.

Symbolic Functions [C++]
++++++++++++++++++++++++
The ``cyclus::toolkit::SymbolicFunction`` class and its derivatives provide an
object-oriented hierarchy to represent symbolic functions. Factory methods are
provided by the ``cyclus::toolkit::SymbFunctionFactory`` class.

Agent Managed Classes [C++]
+++++++++++++++++++++++++++
There are a number of interfaces provided in the |cyclus| toolkit that can be
used as either as `mixins <http://en.wikipedia.org/wiki/Mixin>`_ or as
composable, agent-managed state variables:

* ``cyclus::toolkit::Builder``: an interface for adding information about agents
that can be built by the manager

* ``cyclus::toolkit::BuildingManager``: an interface for making build decisions
based on supply, demand, and agents that can be built

* ``cyclus::toolkit::CommodityProducer``: an interface for adding information
about commodities that can be produced by the manager

* ``cyclus::toolkit::CommodityProducerManager``: an interface that allows an
agent to query a collection of ``cyclus::toolkit::CommodityProducers``

* ``cyclus::toolkit::SupplyDemandManager``: an interface for querying the supply
and demand on commodities

Geographic Informasion System (GIS) Class [C++]
+++++++++++++++++++++++++++++++++++++++++++++++
The ``cyclus::toolkit::GIS`` class provide an option to add geographic coordinates
of its friend classes. Haversine distance calculations between two facilities or
agents with GIS coordinates can be performed as well.
1 change: 0 additions & 1 deletion source/cyclusagent.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ def indent(text, prefix):
def contains_resbuf(type_str):
bufs = ('cyclus::toolkit::ResBuf',
'cyclus::toolkit::ResMap',
'cyclus::toolkit::ResourceBuff',
'cyclus::toolkit::TotalInvTracker')
for buf in bufs:
if buf in type_str:
Expand Down

0 comments on commit 50b43a6

Please sign in to comment.