Adding warnings about YAML file limitations

README.rst

@@ -34,7 +34,7 @@ peak structural temperature in a design-basis transient.
 
 .. note:: ARMI does not come with a full selection of physics kernels. They will need to
    be acquired or developed for your specific project in order to make full use of this
-   tool.  Many of the example use-cases discussed in this manual require functionality
+   tool. Many of the example use-cases discussed in this manual require functionality
    that is not included in the open-source ARMI Framework.
 
 In general, ARMI aims to enhance the quality, ease, and rigor of computational nuclear
@@ -132,7 +132,7 @@ Nuclear reactor design requires, among other things, answers to the following qu
 * How does the building handle earthquakes?
 
 Digital computers have assisted in nuclear technology development since the days of the
-ENIAC in the 1940s.  We now understand reactor physics well enough to build detailed
+ENIAC in the 1940s. We now understand reactor physics well enough to build detailed
 simulations, which can answer many of these design questions in a cost-effective, and
 flexible manner. This allows us to simulate all kinds of different reactors with
 different fuels, coolants, moderators, power levels, safety systems, and power cycles.
@@ -144,7 +144,7 @@ economics, and safety.
 
 Perhaps surprisingly, some nuclear software written in the 1960s is still in use today
 (mostly ported to Fortran 90 by now). These codes are validated against physical
-experiments that no longer exist.  Meanwhile, new cutting-edge nuclear software is being
+experiments that no longer exist. Meanwhile, new cutting-edge nuclear software is being
 developed today for powerful computers. Both old and new, these tools are often
 challenging to operate and to use in concert with other sub-specialty codes that are
 necessary to reach a full system analysis.
@@ -153,7 +153,7 @@ The ARMI approach was born out of this situation: how can we best leverage an ec
 mix of legacy and modern tools with a small team to do full-scope analysis? We built an
 environment that lets us automate the tedious, uncoupled, and error-prone parts of
 reactor engineering/analysis work. We can turn around a very meaningful and detailed
-core analysis given a major change (e.g. change power by 50%) in just a few weeks.  We
+core analysis given a major change (e.g. change power by 50%) in just a few weeks. We
 can dispatch hundreds of parameter sweeps to multiple machines and then perform
 multiobjective optimization on the resulting design space.
 
@@ -190,7 +190,7 @@ Automation
 ----------
 
 ARMI can quickly and easily produce complex input files with high levels of detail in
-various approximations.  This enables users to perform rapid high-fidelity analyses to
+various approximations. This enables users to perform rapid high-fidelity analyses to
 make sure all important physics are captured. It also enables sensitivity studies of
 different modeling approximations (e.g. symmetries, transport vs. diffusion vs. Monte
 Carlo, subchannel vs. CFD, etc.).
@@ -223,7 +223,7 @@ and finding the peak power density is easy::
 
 Any ARMI state can be written out to whichever format the user desires, meaning that
 nominally identical cases can be produced for multiple similar codes in sensitivity
-studies.  To read power densities, simply read them off the assembly objects. Instead of
+studies. To read power densities, simply read them off the assembly objects. Instead of
 producing spreadsheets and making plots manually, analysts may write scripts to generate
 output reports that run automatically.
 
@@ -242,7 +242,7 @@ Use cases
 Given input describing a reactor, a typical ARMI run loops over a set of plugins in a
 certain sequence. Some plugins trigger third-party simulation codes, producing input
 files for them, executing them, and translating the output back onto the reactor model
-as state information. Other plugins perform physics simulations directly.  A variety of
+as state information. Other plugins perform physics simulations directly. A variety of
 plugins are available from TerraPower LLC with certain licensing terms, and it is our
 hope that a rich ecosystem of useful plugins will be developed and curated by the
 community (university research teams, national labs, other companies, etc.).
@@ -266,7 +266,7 @@ For example, one ARMI sequence may involve the calculation of:
   transients.
 
 Another sequence may simply compute the cost of feed uranium and enrichment in an
-initial core and quit.  The possibilities are limited only by our creativity.
+initial core and quit. The possibilities are limited only by our creativity.
 
 These large runs may also be run through the multiobjective design optimization system,
 which runs many cases with input perturbations to help find the best overall system,
@@ -322,7 +322,7 @@ ARMI was originally created by TerraPower, LLC near Seattle WA starting in 2009.
 founding mission was to determine the optimal fuel management operations required to
 transition a fresh Traveling Wave Reactor core from startup into an equilibrium state.
 It started out automating the Argonne National Lab (ANL) fast reactor neutronics codes,
-MC2 and REBUS.  The reactor model design was made with the intention of adding other
+MC2 and REBUS. The reactor model design was made with the intention of adding other
 physics capabilities later. Soon, simple thermal hydraulics were added and it's grown
 ever since. It has continuously evolved towards a general reactor analysis framework.
 
@@ -331,16 +331,16 @@ architecture for ARMI, allowing some of the intertwined physics capabilities to
 separated out as plugins from the standalone framework.
 
 The nuclear industry is small, and it faces many challenges. It also has a tradition of
-secrecy.  As a result, there is risk of overlapping work being done by other entities.
+secrecy. As a result, there is risk of overlapping work being done by other entities.
 
 We hypothesize that collaborating on software systems can help align some efforts
 worldwide, increasing quality and efficiency. In reactor development, the idea is
-generally cheap.  It's the shakedown, technology and supply chain development,
+generally cheap. It's the shakedown, technology and supply chain development,
 engineering demo, and commercial demo that are the hard parts.
 
 Thus, ARMI was released under an open-source license in 2019 to facilitate mutually
 beneficial collaboration across the nuclear industry, where many teams are independently
-developing similar reactor analysis/automation frameworks.  TerraPower will make its
+developing similar reactor analysis/automation frameworks. TerraPower will make its
 proprietary analysis routines, physics kernels, and material properties available under
 commercial licenses.
 
@@ -381,16 +381,15 @@ needs of thermal reactors (like a good spatial description of pin maps) exists b
 has not been subject to as much use.
 
 ARMI was developed within a rapidly changing R&D environment. It evolved accordingly,
-and naturally carries some legacy.  We continuously attempt to identify and update
-problematic parts of the code.  Users should understand that ARMI is not a polished
-consumer software product, but rather a powerful and flexible engineering tool.  It has
+and naturally carries some legacy. We continuously attempt to identify and update
+problematic parts of the code. Users should understand that ARMI is not a polished
+consumer software product, but rather a powerful and flexible engineering tool. It has
 the potential to accelerate work on many kinds of reactors. But in many cases, it will
 require serious and targeted investment.
 
 ARMI was largely written by nuclear and mechanical engineers. We (as a whole) only
 really, truly, recognized the value of things like static typing in a complex system
-like ARMI somewhat recently.  Contributions from software engineers are *more than*
-welcome!
+like ARMI somewhat recently.
 
 ARMI has been written to support specific engineering/design tasks. As such, polish in
 the GUIs and output is somewhat lacking.
@@ -427,7 +426,7 @@ Be careful when including any dependency in ARMI (say in the ``pyproject.toml``
 to include anything with a license that superceeds our Apache license. For instance,
 any third-party Python library included in ARMI with a GPL license will make the whole
 project fall under the GPL license. But a lot of potential users of ARMI will want to
-keep some of their work private, so we can't allow any GPL tools.
+keep some of their work private, so we can't allow any GPL dependencies.
 
 For that reason, it is generally considered best-practice in the ARMI ecosystem to
 only use third-party Python libraries that have MIT or BSD licenses.

doc/user/inputs.rst

@@ -2,11 +2,10 @@
 Inputs
 ******
 
-ARMI input files define the initial state of the reactor model and tell ARMI what kind of analysis should be
-performed on it.
+ARMI input files define the initial state of the reactor model and tell ARMI what kind of analysis
+should be performed on it.
 
-.. note:: We have a :ref:`walkthrough-inputs` tutorial for a quick 
-    overview of the inputs.
+.. note:: We have a :ref:`walkthrough-inputs` tutorial for a quick overview of the inputs.
 
 There are several input files:
 
@@ -15,24 +14,39 @@ Settings file
   	activate) and all kind of modeling approximation settings (e.g. convergence criteria)
 
 Blueprints file
-	Contains dimensions and composition of the components/blocks/assemblies in your reactor systems, from fuel 
-  	pins to heat exchangers
+	Contains dimensions and composition of the components/blocks/assemblies in your reactor systems,
+    from fuel pins to heat exchangers
 
 Fuel management file
 	Describes how fuel moves around during a simulation
 
 
-Depending on the type of analysis, there may be additional inputs required. These include things like
-control logic, ex-core models for transients and shielding, etc.
+Depending on the type of analysis, developers may create other input files for things like: control
+logic, ex-core models for transients and shielding, etc.
 
-The core map input files can be graphically manipulated with the 
-:py:mod:`Grid editor <armi.utils.gridEditor>`.
+
+YAML Files
+==========
+ARMI's input files all use the `YAML <https://en.wikipedia.org/wiki/YAML>`_ format. This is a well-
+known file format, chosen because it is human-readable and easy to hand-write. That being said,
+there are two details about the YAML format it is important to know:
+
+Ordering
+    YAML is not order specific; however, one of the techniques used to limit the size of the input
+    includes using YAML anchors to resuse block and component definitions. YAML anchors (e.g.
+    ``&block_name``) must be defined before their corresponding alias (e.g. ``*block_name``) used.
+
+Duplicate Keys
+    YAML allows for duplicate keys. However, in ARMI, duplicates might be erroneous. Unfortunately,
+    because the international YAML specification allows for duplicates, none of the YAML-parsing
+    libraries see it as an error. You will have to hand-verify your inputs are correct.
 
 
 The Settings Input File
 =======================
-The **settings** input file defines a series of key/value pairs the define various information about the system you are
-modeling as well as which modules to run and various modeling/approximation settings. For example, it includes:
+The **settings** input file defines a series of key/value pairs the define various information about
+the system you are modeling as well as which modules to run and various modeling/approximation
+settings. For example, it includes:
 
 * The case title
 * The reactor power
@@ -52,21 +66,23 @@ Here is an excerpt from a settings file:
     :language: yaml
     :lines: 3-15
 
-A full listing of settings available in the framework may be found in the `Table of all global settings <#settings-report>`_ .
+A full listing of settings available in the framework may be found in the
+`Table of all global settings <#settings-report>`_ .
 
 Many settings are provided by the ARMI Framework, and others are defined by various plugins.
 
 .. _armi-gui:
 
 The ARMI GUI
 ------------
-The ARMI GUI may be used to manipulate many common settings (though the GUI can't change all of the settings).  The GUI
-also enables the graphical manipulation of a reactor core map, and convenient automation of commands required to submit to a
-cluster.  The GUI is a front-end to
-these files. You can choose to use the GUI or not, ARMI doesn't know or care --- it just reads these files and runs them.
+The ARMI GUI may be used to manipulate many common settings (though the GUI can't change all of the
+settings).  The GUI also enables the graphical manipulation of a reactor core map, and convenient
+automation of commands required to submit to a cluster.  The GUI is a front-end to these files. You
+can choose to use the GUI or not, ARMI doesn't know or care --- it just reads these files and runs
+them.
 
-Note that one settings input file is required for each ARMI case, though many ARMI cases can refer to the same
-Blueprints, Core Map, and Fuel Management inputs.
+Note that one settings input file is required for each ARMI case, though many ARMI cases can refer
+to the same Blueprints, Core Map, and Fuel Management inputs.
 
 .. tip:: The ARMI GUI is not yet included in the open-source ARMI framework
 
@@ -481,11 +497,8 @@ The ARMI data model is represented schematically below, and the blueprints are d
 :ref:`custom isotopics <custom-isotopics>`:
     Special setting: defines user-specified isotopic compositions.
 
-.. warning::
-
-    YAML is not order specific; however, one of the techniques used to limit the size of the input
-    includes using YAML anchors to resuse block and component definitions. YAML anchors (e.g.
-    ``&block_name``) must be defined before their corresponding alias (e.g. ``*block_name``) used.
+The core map input files can be graphically manipulated with the 
+:py:mod:`Grid editor <armi.utils.gridEditor>`.
 
 
 .. _blocks-and-components: