From 42392dd2eed937b5c0cd8beacdfc2e75c5f7fac8 Mon Sep 17 00:00:00 2001 From: bennibbelink <79653949+bennibbelink@users.noreply.github.com> Date: Sat, 3 Aug 2024 16:56:07 -0400 Subject: [PATCH] add documentation for cyclus constants --- source/arche/constants.rst | 71 ++++++++++++++++ source/arche/tutorial_cpp/state_var.rst | 107 +++++++++++++----------- 2 files changed, 127 insertions(+), 51 deletions(-) create mode 100644 source/arche/constants.rst diff --git a/source/arche/constants.rst b/source/arche/constants.rst new file mode 100644 index 000000000..f5f919390 --- /dev/null +++ b/source/arche/constants.rst @@ -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::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; diff --git a/source/arche/tutorial_cpp/state_var.rst b/source/arche/tutorial_cpp/state_var.rst index 78acfb0ab..3ca2b0d35 100644 --- a/source/arche/tutorial_cpp/state_var.rst +++ b/source/arche/tutorial_cpp/state_var.rst @@ -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; @@ -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 --------------------------------------- @@ -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 @@ -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