Skip to content

Commit

Permalink
add documentation for cyclus constants
Browse files Browse the repository at this point in the history
  • Loading branch information
@bennibbelink
bennibbelink committed Aug 3, 2024
1 parent b76d431 commit 42392dd
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 51 deletions.
71 changes: 71 additions & 0 deletions source/arche/constants.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
.. _constants:

Using standard constants in |Cyclus|
======================================

Cyclus defines a set of constants to help standardize archetype properties and prevent
unexpected simulation failures. These constants are determined at build time and may
depend on your system's architecture (e.g. for maximum integer size). This set is
defined twice, with identical values existing in the C++ namespace and Python library.
The numeric values are as follows:

.. list-table:: Cyclus constant values
:widths: 25 25 25
:header-rows: 1

* - Name
- Value
* - CY_LARGE_INT
- 2147483647 (on most 64-bit machines; this should be equal to std::numeric_limits<int>::max())
* - CY_LARGE_DOUBLE
- 1e299
* - CY_NEAR_ZERO
- 1e-08

Accessing constants in C++
--------------------------

The constants are defined in ``cyclus/cyc_limits.h`` and exist in the ``cyclus::`` namespace. They can be
included and used as so:

.. code-block:: cpp
#include "cyclus.h"
...
double my_large_double = cyclus::CY_LARGE_DOUBLE;
...
Accessing constants in Python
-----------------------------

The constants are defined in the ``cyclus.system`` module and can be imported and used as long as
the cyclus package is in your Python path:

.. code-block:: python
from cyclus.system import CY_LARGE_DOUBLE, CY_LARGE_INT, CY_NEAR_ZERO
...
my_small_value = CY_NEAR_ZERO
...
Using constants with the Cyclus Preprocessor
--------------------------------------------

Many archetype developers utilize the Cyclus Preprocessor and ``#pragma cyclus`` to
define state variables within an archetype. The preprocessor allows any arbitrary
Python code to be executed via ``#pragma cyclus exec``. Thus one can import the
set of Python constants into the global namespace that agent annotations are processed,
and reference them in state variable definitions. Remember that the object
following ``#pragma cyclus var`` is evaluated by the Python interpreter, so you can
treat it as if it were Python code.

.. code-block:: cpp
#pragma cyclus exec from cyclus.system import CY_LARGE_DOUBLE
...
#pragma cyclus var {"default": CY_LARGE_DOUBLE, \
"tooltip": "sink maximum inventory size", \
"uilabel": "Maximum Inventory", \
"uitype": "range", \
"range": [0.0, CY_LARGE_DOUBLE], \
"doc": "total maximum inventory size of sink facility"}
double max_inv_size;
107 changes: 56 additions & 51 deletions source/arche/tutorial_cpp/state_var.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ stored and the input/output commodity names.
"doc": "Minimum amount of time material must be stored", \
"tooltip": "Minimum amount of time material must be stored", \
"units": "months", \
"uilabel": "Storage Time" \
"uilabel": "Storage Time" \
}
int storage_time;

Expand All @@ -58,6 +58,11 @@ stored and the input/output commodity names.
}
std::string outcommod;

.. note::
Sometimes you may wish to include numeric values in your state variable definitions,
such as a default value or range of possible values. Cyclus provides a set of constants
that might be of use, see :ref:`constants` for more information.

Build and Install the Modified Module
---------------------------------------

Expand All @@ -78,33 +83,33 @@ to define your module. It is missing the new variables. Try it:
.. code-block:: console
$ cyclus -v 2 input/storage.xml
:
.CL:CC CC _Q _Q _Q_Q _Q _Q _Q
CC;CCCCCCCC:C; /_\) /_\)/_/\\) /_\) /_\) /_\)
:
.CL:CC CC _Q _Q _Q_Q _Q _Q _Q
CC;CCCCCCCC:C; /_\) /_\)/_/\\) /_\) /_\) /_\)
CCCCCCCCCCCCCl __O|/O___O|/O_OO|/O__O|/O__O|/O____________O|/O__
CCCCCCf iCCCLCC /////////////////////////////////////////////////
iCCCt ;;;;;. CCCC
CCCC ;;;;;;;;;. CClL. c
CCCC ,;; ;;: CCCC ; : CCCCi
CCC ;; ;; CC ;;: CCC` `C;
lCCC ;; CCCC ;;;: :CC .;;. C; ; : ; :;;
CCCC ;. CCCC ;;;, CC ; ; Ci ; : ; : ;
iCC :; CC ;;;, ;C ; CC ; : ; .
CCCi ;; CCC ;;;. .C ; tf ; : ; ;.
CCC ;; CCC ;;;;;;; fC : lC ; : ; ;:
iCf ;; CC :;;: tC ; CC ; : ; ;
fCCC :; LCCf ;;;: LC :. ,: C ; ; ; ; ;
CCCC ;; CCCC ;;;: CCi `;;` CC. ;;;; :;.;. ; ,;
CCl ;; CC ;;;; CCC CCL
tCCC ;; ;; CCCL ;;; tCCCCC.
CCCC ;; :;; CCCCf ; ,L
lCCC ;;;;;; CCCL
CCCCCC :;; fCCCCC
. CCCC CCCC .
.CCCCCCCCCCCCCi
iCCCCCLCf
. C. ,
:
iCCCt ;;;;;. CCCC
CCCC ;;;;;;;;;. CClL. c
CCCC ,;; ;;: CCCC ; : CCCCi
CCC ;; ;; CC ;;: CCC` `C;
lCCC ;; CCCC ;;;: :CC .;;. C; ; : ; :;;
CCCC ;. CCCC ;;;, CC ; ; Ci ; : ; : ;
iCC :; CC ;;;, ;C ; CC ; : ; .
CCCi ;; CCC ;;;. .C ; tf ; : ; ;.
CCC ;; CCC ;;;;;;; fC : lC ; : ; ;:
iCf ;; CC :;;: tC ; CC ; : ; ;
fCCC :; LCCf ;;;: LC :. ,: C ; ; ; ; ;
CCCC ;; CCCC ;;;: CCi `;;` CC. ;;;; :;.;. ; ,;
CCl ;; CC ;;;; CCC CCL
tCCC ;; ;; CCCL ;;; tCCCCC.
CCCC ;; :;; CCCCf ; ,L
lCCC ;;;;;; CCCL
CCCCCC :;; fCCCCC
. CCCC CCCC .
.CCCCCCCCCCCCCi
iCCCCCLCf
. C. ,
:
Entity: line 17: element Storage: Relax-NG validity error : Expecting an element throughput, got nothing
Entity: line 17: element Storage: Relax-NG validity error : Invalid sequence in interleave
Entity: line 17: element Storage: Relax-NG validity error : Element Storage failed to validate content
Expand Down Expand Up @@ -155,33 +160,33 @@ Now we can try it again:
.. code-block:: console
$ cyclus -v 2 input/storage.xml
:
.CL:CC CC _Q _Q _Q_Q _Q _Q _Q
CC;CCCCCCCC:C; /_\) /_\)/_/\\) /_\) /_\) /_\)
:
.CL:CC CC _Q _Q _Q_Q _Q _Q _Q
CC;CCCCCCCC:C; /_\) /_\)/_/\\) /_\) /_\) /_\)
CCCCCCCCCCCCCl __O|/O___O|/O_OO|/O__O|/O__O|/O____________O|/O__
CCCCCCf iCCCLCC /////////////////////////////////////////////////
iCCCt ;;;;;. CCCC
CCCC ;;;;;;;;;. CClL. c
CCCC ,;; ;;: CCCC ; : CCCCi
CCC ;; ;; CC ;;: CCC` `C;
lCCC ;; CCCC ;;;: :CC .;;. C; ; : ; :;;
CCCC ;. CCCC ;;;, CC ; ; Ci ; : ; : ;
iCC :; CC ;;;, ;C ; CC ; : ; .
CCCi ;; CCC ;;;. .C ; tf ; : ; ;.
CCC ;; CCC ;;;;;;; fC : lC ; : ; ;:
iCf ;; CC :;;: tC ; CC ; : ; ;
fCCC :; LCCf ;;;: LC :. ,: C ; ; ; ; ;
CCCC ;; CCCC ;;;: CCi `;;` CC. ;;;; :;.;. ; ,;
CCl ;; CC ;;;; CCC CCL
tCCC ;; ;; CCCL ;;; tCCCCC.
CCCC ;; :;; CCCCf ; ,L
lCCC ;;;;;; CCCL
CCCCCC :;; fCCCCC
. CCCC CCCC .
.CCCCCCCCCCCCCi
iCCCCCLCf
. C. ,
:
iCCCt ;;;;;. CCCC
CCCC ;;;;;;;;;. CClL. c
CCCC ,;; ;;: CCCC ; : CCCCi
CCC ;; ;; CC ;;: CCC` `C;
lCCC ;; CCCC ;;;: :CC .;;. C; ; : ; :;;
CCCC ;. CCCC ;;;, CC ; ; Ci ; : ; : ;
iCC :; CC ;;;, ;C ; CC ; : ; .
CCCi ;; CCC ;;;. .C ; tf ; : ; ;.
CCC ;; CCC ;;;;;;; fC : lC ; : ; ;:
iCf ;; CC :;;: tC ; CC ; : ; ;
fCCC :; LCCf ;;;: LC :. ,: C ; ; ; ; ;
CCCC ;; CCCC ;;;: CCi `;;` CC. ;;;; :;.;. ; ,;
CCl ;; CC ;;;; CCC CCL
tCCC ;; ;; CCCL ;;; tCCCCC.
CCCC ;; :;; CCCCf ; ,L
lCCC ;;;;;; CCCL
CCCCCC :;; fCCCCC
. CCCC CCCC .
.CCCCCCCCCCCCCi
iCCCCCLCf
. C. ,
:
INFO1(core ):Simulation set to run from start=0 to end=10
INFO1(core ):Beginning simulation
INFO1(tutori):Hello
Expand Down

0 comments on commit 42392dd

Please sign in to comment.