From efa34128d3063f41fa76fcd0ae31c1a3e3cc6b70 Mon Sep 17 00:00:00 2001
From: Ben Nibbelink <bnibbs@vt.edu>
Date: Wed, 7 Aug 2024 22:02:51 -0400
Subject: [PATCH] add notes about using constants in input files

---
 source/arche/constants.rst    | 19 +++++++++++++++++++
 source/user/writing_input.rst |  6 +++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/source/arche/constants.rst b/source/arche/constants.rst
index e98e955a6..8c1075a11 100644
--- a/source/arche/constants.rst
+++ b/source/arche/constants.rst
@@ -50,6 +50,25 @@ the ``cyclus`` package is in your Python path:
   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
 --------------------------------------------
 
diff --git a/source/user/writing_input.rst b/source/user/writing_input.rst
index 5ac25c451..7379becf0 100644
--- a/source/user/writing_input.rst
+++ b/source/user/writing_input.rst
@@ -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: