Skip to content

Commit

Permalink
Merge pull request #381 from bennibbelink/constant-docs-origin
Browse files Browse the repository at this point in the history 
Add docs for new constants
  • Loading branch information
@gonuke
gonuke authored Sep 10, 2024
2 parents b76d431 + efa3412 commit 3461fd8
Show file tree
Hide file tree
Showing 4 changed files with 156 additions and 53 deletions.
1 change: 0 additions & 1 deletion docker/Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
FROM ghcr.io/cyclus/cymetric_22.04_conda/cymetric:latest

RUN mamba update -y --all
RUN mamba install -y sphinx sphinxcontrib-bibtex cloud_sptheme
95 changes: 95 additions & 0 deletions source/arche/constants.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
.. _constants:

|Cyclus| Defined Constants
======================================

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 (specifically the size of an ``int`` type, in bytes).
This set is defined twice, with identical values existing in the C++ namespace and Python library.
The numeric values are as follows:

.. list-table::
:width: 100%
:widths: 25 75
: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
used in this way:

.. code-block:: cpp
#include "cyclus.h"
...
int my_large_int = cyclus::CY_LARGE_INT;
...
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
...
This holds true for |Cyclus| input files:

.. code-block:: python
from cyclus.system import CY_LARGE_DOUBLE
SIMULATION = { 'simulation':
...
'facility': [
{ 'config':
{ 'Source':
{ 'capacity': CY_LARGE_DOUBLE,
...
.. warning::
Only input files written in Python can access the constants in this way, since the variables are evaluated
prior to schema validation. Any attempt to use them in an XML input file will likely fail schema validation since
they will be evaluated as strings instead of the corresponding values in C++/Python.
Using constants with the Cyclus Preprocessor
--------------------------------------------
Many archetype developers utilize the :ref:`Cyclus Preprocessor <cycpp>` 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:`documentation on standard constants <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
6 changes: 5 additions & 1 deletion source/user/writing_input.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,12 +115,16 @@ contains all data for a simulation.
# dictionary with a single "simulation" key.
simulation = {"simulation": {...}}
# Alternitavely, the simualtion variable can also be a Python function or
# Alternatively, the simulation variable can also be a Python function or
# callable that returns a simulation dictionary. This function should not
# take any arguments.
def simulation():
return {"simulation": {...}}
.. note::
Some :ref:`constants <constants>` are provided by |Cyclus| and can be leveraged in Python input files.
Keep them in mind when defining near-zero values, or very large integer/double values. This
can help keep your simulation within the constraints of the program and avoid runtime errors.

Although not all sections are required, the following sections may appear in
any order in the input file:
Expand Down

0 comments on commit 3461fd8

Please sign in to comment.