Skip to content

Commit

Permalink
Pyagent Documentation (cyclus#230)
Browse files Browse the repository at this point in the history 
LGTM!

thx @scopatz
  • Loading branch information
@scopatz @bam241
scopatz authored and bam241 committed Feb 9, 2017
1 parent 22635de commit 1d76798
Show file tree
Hide file tree
Showing 47 changed files with 2,155 additions and 593 deletions.
44 changes: 25 additions & 19 deletions source/arche/cli.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

Archetype Command Line Interface
=======================================

There are a few archetype-specific |Cyclus| CLI commands that allow
introspecting details of archetypes that |Cyclus| can find. Most expose data
that is automatically generated by the Cyclus preprocessor. For example,
Expand Down Expand Up @@ -39,15 +38,15 @@ To view a JSON structured output of all the data generated and collected from
$ cyclus --agent-annotations :cycamore:Source
{
"all_parents": [
"cyclus::Agent",
"cyclus::Facility",
"cyclus::Ider",
"cyclus::StateWrangler",
"cyclus::TimeListener",
"cyclus::Trader",
"cyclus::toolkit::AgentManaged",
"cyclus::Agent",
"cyclus::Facility",
"cyclus::Ider",
"cyclus::StateWrangler",
"cyclus::TimeListener",
"cyclus::Trader",
"cyclus::toolkit::AgentManaged",
"cyclus::toolkit::CommodityProducer"
],
],
"doc": "This facility acts as a source of material with a fixed...
...
Expand All @@ -69,26 +68,33 @@ And to list all archetypes inside a particular library:
Archetype Versioning
--------------------
The ``cyclus::Agent`` class exposes a ``version()`` member function which can be
queried with the |Cyclus| CLI. For example,
queried with the |Cyclus| CLI. For example,
.. code-block:: bash
.. code-block:: bash
$ cyclus --agent-version :agents:Source
1.3.1-7-g9a2c9c9
$ cyclus --agent-version :agents:Source
1.3.1-7-g9a2c9c9
This is generated from some ``git`` version control information. You can make
your own version tag information for some archetype like
**C++:**
.. code-block:: c++
.. code-block:: c++
virtual std::string version() { return "My Version"; }
virtual std::string version() { return "My Version"; }
**Python:**
.. code-block:: Python
def version(self):
return "My Version"
and then access the version with
.. code-block:: bash
.. code-block:: bash
$ cyclus --agent-version my/path:my_library:MyArchetype
My Version
$ cyclus --agent-version my/path:my_library:MyArchetype
My Version
60 changes: 53 additions & 7 deletions source/arche/custom_tables.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@

Custom Database Tables
=======================

Agents are allowed to write their own custom output into the database during
simulations. The interface for recording this data is accessible through the
agent's :term:`context`. Data may be logged via the Context::NewDatum function:

**C++:**

.. code-block:: c++

MyReactor::Tick() {
Expand All @@ -22,17 +23,38 @@ agent's :term:`context`. Data may be logged via the Context::NewDatum function:
...
}

**Python:**

.. code-block:: python
from cyclus.agents import Facility
import cyclus.typesystem as ts
class MyReactor(Facility):
def tick(self):
...
d = self.context.new_datum("MyReactorData")
d.add_val("AgentID", self.id, type=ts.INT)
d.add_val("Time", self.context.time, type=ts.INT)
d.add_val("WaterUsage", self.monthl_water, type=ts.DOUBLE)
d.add_val("OperatingCost", self.monthly_op_cost, type=ts.DOUBLE)
d.record()
...
This would create a table in the output database named "MyReactorData". The
table would get a new row entry every time step with four columns named
"AgentID", "Time", "WaterUsage" and "OperatingCost". ``AddVal`` calls can be chained
any number of times for an arbitrary number of columns. ``Record`` must be
"AgentID", "Time", "WaterUsage" and "OperatingCost". "Add value" calls can be chained
any number of times for an arbitrary number of columns. Record must be
called once for each datum after all values have been added. Any custom
tables created in this manner will appear in the output database alongside the
|cyclus| core tables. Because there may be several agent instances of a
single agent class, tables should generally include a column that adds their
ID; and for similar reasons, it is often desirable to include the simulation
time as a column in these tables:

**C++:**

.. code-block:: c++

context()->NewDatum("MyReactorData")
Expand All @@ -41,6 +63,16 @@ time as a column in these tables:
->AddVal(...
...

**Python:**

.. code-block:: python
d = self.context.new_datum("MyReactorData")
d.add_val("AgentID", self.id, type=ts.INT)
d.add_val("Time", self.context.time, type=ts.INT)
d.add_val(...
...
Datums with the same table name must have the same schema (e.g. same field
names and value types). It is the responsibility of the developer to
enforce this in their code.
Expand All @@ -53,8 +85,8 @@ enforce this in their code.
use. For information on which c++ types the backends support, you can check
:doc:`here <dbtypes>`.
.. note:: If you require a datatype that isn't currently supported, please
ask the kernel developers and they will help as soon as possible.
.. note:: If you require a datatype that isn't currently supported, please
ask the kernel developers and they will help as soon as possible.
Table Data Shapes
------------------
Expand All @@ -70,6 +102,8 @@ vector indicates variable length also. It is an error to pass in a shape
vector with the wrong rank (number of elements) for that type. An example of
using the shape vector follows:
**C++:**
.. code-block:: c++
std::vector<std::string> colors;
Expand All @@ -84,15 +118,27 @@ using the shape vector follows:
context()->NewDatum("DecorPreferences")
->AddVal("AgentID", id())
->AddVal("Time", context()->time())
->AddVal("FavoritColors", colors, shape)
->AddVal("FavoriteColors", colors, shape)
->Record();
**Python:**
.. code-block:: c++
colors = ["green", "blue", "chartreuse"]
shape = [5, 8]
d = self.context.new_datum("DecorPreferences")
d.add_val("AgentID", self.id, type=ts.INT)
d.add_val("Time", self.context.time, type=ts.INT)
d.add_val("FavoriteColors", colors, shape, ts.VECTOR_STRING)
d.record()
In the example above, the "chartreuse" color is longer than the 8 characters
specified in the shape. So it will be truncated to "chartreu" in the
database. Shape vectors should generally be stored as class member variables
to avoid excessive memory [de]allocation and should be set correctly from
construction to destruction of your agent.
Reserved Table Names
---------------------
Expand Down
22 changes: 11 additions & 11 deletions source/arche/dbtypes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Database Types
==============

Here is a listing of all supported data types that the various backends have
implemented, by |cyclus| version number. If your agents need a type that is not
Here is a listing of all supported data types that the various backends have
implemented, by |cyclus| version number. If your agents need a type that is not
yet supported, please let us know and we'll get to it as soon as possible!

**Description of fields:**
Expand All @@ -29,7 +29,7 @@ yet supported, please let us know and we'll get to it as soon as possible!

<style>
p {
font-size: 100%;
font-size: 100%;
}
img {
Expand All @@ -52,7 +52,7 @@ yet supported, please let us know and we'll get to it as soon as possible!
var dbdata = []
$.getJSON("/arche/dbtypes.json", function(json) {
dbdata = json;
function setupPivot(input){
input.callbacks = {afterUpdateResults: function(){
$('#results > table').dataTable({
Expand All @@ -72,16 +72,16 @@ yet supported, please let us know and we'll get to it as soon as possible!
fields =[{name: 'id', type: 'integer', filterable: true},
{name: 'name', type: 'string', filterable: true,
displayFunction: function(value){
return '<div style="font-family:Courier,monospace;">' +
return '<div style="font-family:Courier,monospace;">' +
value + '</div>';}},
{name: "C++ type", type: 'string', filterable: true,
displayFunction: function(value){
return '<div style="font-family:Courier,monospace;">' +
return '<div style="font-family:Courier,monospace;">' +
value + '</div>';}},
{name: 'shape rank', type: 'integer', filterable: true},
{name: 'backend', type: 'string', filterable: true,
{name: 'backend', type: 'string', filterable: true,
columnLabelable: true},
{name: 'version', type: 'string', filterable: true,
{name: 'version', type: 'string', filterable: true,
columnLabelable: true},
{name: 'supported', type: 'integer', filterable: true,
rowLabelable: true, summarizable: 'sum',
Expand All @@ -90,15 +90,15 @@ yet supported, please let us know and we'll get to it as soon as possible!
return '<div style="text-align:center;' +
'background-color:#c8e8b0">Yes</div>';
else
return '<div style="text-align:center;' +
return '<div style="text-align:center;' +
'background-color:#fcf1df">No</div>';
}
}
];
setupPivot({json: dbdata, fields: fields,
filters: {version: "v1.2"},
rowLabels: ["C++ type"],
filters: {version: "v1.2"},
rowLabels: ["C++ type"],
columnLabels: ["backend"],
summaries: ["supported_sum"]});
Expand Down
24 changes: 11 additions & 13 deletions source/arche/decay.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
Radioactive Decay in |Cyclus|
=============================

.. warning:: Decay in |cyclus| is experimental.

Radioactive decay of a group of isotopes over time can be described by the
Expand All @@ -28,7 +27,6 @@ is explained in more detail below.

The Uniformization Method
-------------------------

The Uniformization Method is essentially a modification of the truncated Taylor
Series expansion of the matrix exponential solution, which can be described by
the following summation:
Expand All @@ -51,7 +49,7 @@ The first step in applying the uniformization technique is to define
element of `A`:

.. math::
\alpha=max_i\left | {a_i}_i \right |
Then, given `alpha`, the next step is to redefine the matrix
Expand Down Expand Up @@ -114,15 +112,15 @@ in an even lower maximum time scale.
References
----------

#. Cleve Moler and Charles van Loan, "Nineteen Dubious Ways to Compute the
Exponential of a Matrix, Twenty-Five Years Later," *SIAM Review*, *45*,
3-49 (2003)
#. Cleve Moler and Charles van Loan, "Nineteen Dubious Ways to Compute the
Exponential of a Matrix, Twenty-Five Years Later," *SIAM Review*, *45*,
3-49 (2003)

#. Erwin Muller, Frederik Reitsma and Paulus P. Kruger, "A Stable Nuclide
Transmutation Procedure Free of Numerical Roundoff," *PHYSOR 2006*, September
10-14, Vancouver, Canada (2006)

#. Erwin Muller, Frederik Reitsma and Paulus P. Kruger, "A Stable Nuclide
Transmutation Procedure Free of Numerical Roundoff," *PHYSOR 2006*, September
10-14, Vancouver, Canada (2006)
#. R. B. Sidje and W. J. Stewart, "A numerical study of large sparse matrix
exponentials arising in Markov chains," *Computational Statistics & Data
Analysis*, *29*, 345-368 (1999)

#. R. B. Sidje and W. J. Stewart, "A numerical study of large sparse matrix
exponentials arising in Markov chains," *Computational Statistics & Data
Analysis*, *29*, 345-368 (1999)

Loading

0 comments on commit 1d76798

Please sign in to comment.