Update diff tally docs

docs/source/usersguide/input.rst

@@ -1708,25 +1708,11 @@ The ``<tally>`` element accepts the following sub-elements:
      *Default*: "all"
 
   :derivative:
-    Tally the first-order derivative of the quantity of interest with respect to
-    some material perturbation. Differential tallies are currently only
-    implemented for collision and analog estimators.
+    The id of a ``derivative`` element. This derivative will be applied to all
+    scores in the tally. Differential tallies are currently only implemented
+    for collision and analog estimators.
 
-    The ``derivative`` element has the following attributes/sub-elements:
-
-      :variable:
-        The independent variable of the derivative. Accepted options are
-        "density" and "nuclide_density". A "density" derivative will give the
-        derivative with respect to the density of the material in [g / cm^3]. A
-        "nuclide_density" derivative will give the derivative with respect to
-        the density of a particular nuclide in units of [atom / b / cm].
-
-      :material:
-        The perturbed material. (Necessary for both "density" and
-        "nuclide_density")
-
-      :nuclide:
-        The perturbed nuclide. (Necessary only for "nuclide_density")
+     *Default*: None
 
 ``<mesh>`` Element
 ------------------
@@ -1756,6 +1742,34 @@ attributes/sub-elements:
       One of ``<upper_right>`` or ``<width>`` must be specified, but not both
       (even if they are consistent with one another).
 
+``<derivative>`` Element
+------------------------
+
+OpenMC can take the first-order derivative of many tallies with respect to
+material perturbations. It works by propagating a derivative through the
+transport equation. Essentially, OpenMC keeps track of how each particle's
+weight would change as materials are perturbed, and then accounts for that
+weight change in the tallies. Note that this assumes material perturbations are
+small enough not to change the distribution of fission sites. This element has
+the following attributes/sub-elements:
+
+  :id:
+    A unique integer that can be used to identify the derivative.
+
+  :variable:
+    The independent variable of the derivative. Accepted options are
+    "density" and "nuclide_density". A "density" derivative will give the
+    derivative with respect to the density of the material in [g / cm^3]. A
+    "nuclide_density" derivative will give the derivative with respect to
+    the density of a particular nuclide in units of [atom / b / cm].
+
+  :material:
+    The perturbed material. (Necessary for both "density" and
+    "nuclide_density")
+
+  :nuclide:
+    The perturbed nuclide. (Necessary only for "nuclide_density")
+
 ``<assume_separate>`` Element
 -----------------------------
 

docs/source/usersguide/output/statepoint.rst

@@ -156,6 +156,18 @@ if run_mode == 'k-eigenvalue':
 
     Width of each mesh cell in each dimension.
 
+**/tallies/derivatives/derivative <id>/independent variable** (*char[]*)
+
+    Independent variable of tally derivative
+
+**/tallies/derivatives/derivative <id>/material** (*int*)
+
+    ID of the perturbed material
+
+**/tallies/derivatives/derivative <id>/nuclide** (*char[]*)
+
+    Alias of the perturbed nuclide
+
 **/tallies/n_tallies** (*int*)
 
     Number of user-defined tallies.
@@ -198,6 +210,10 @@ if run_mode == 'k-eigenvalue':
     Array of nuclides to tally. Note that if no nuclide is specified in the user
     input, a single 'total' nuclide appears here.
 
+**/tallies/tally <uid>/derivative** (*int*)
+
+    ID of the derivative applied to the tally.
+
 **/tallies/tally <uid>/n_score_bins** (*int*)
 
     Number of scoring bins for a single nuclide. In general, this can be greater

openmc/statepoint.py

@@ -468,7 +468,7 @@ class StatePoint(object):
                     base = 'tallies/derivatives/derivative {:d}'.format(d_id)
                     deriv = openmc.TallyDerivative(derivative_id=d_id)
                     deriv.variable = \
-                         self._f[base + '/dependent variable'].value.decode()
+                         self._f[base + '/independent variable'].value.decode()
                     if deriv.variable == 'density':
                         deriv.material = self._f[base + '/material'].value
                     elif deriv.variable == 'nuclide_density':

src/constants.F90

@@ -352,7 +352,7 @@ module constants
        K_TRACKLENGTH = 3, &
        LEAKAGE       = 4
 
-  ! Differential tally dependent variables
+  ! Differential tally independent variables
   integer, parameter :: &
        DIFF_DENSITY = 1, &
        DIFF_NUCLIDE_DENSITY = 2

src/input_xml.F90

@@ -2570,7 +2570,7 @@ contains
                // trim(to_str(deriv % id)))
         end do
 
-        ! Read the dependent variable name.
+        ! Read the independent variable name.
         temp_str = ""
         call get_node_value(node_deriv, "variable", temp_str)
         temp_str = to_lower(temp_str)

src/relaxng/tallies.rnc

@@ -15,6 +15,21 @@ element tallies {
     )
   }* &
 
+  element derivative {
+    (element id { xsd:int } | attribute id { xsd:int }) &
+    (element material { xsd:int } | attribute material { xsd:int }) &
+    ( (element variable { ( "density") }
+        | attribute variable { ( "density" ) } ) |
+      (
+        (element variable { ( "nuclide_density" ) }
+          | attribute variable { ( "nuclide_density" ) } )
+        &
+        (element nuclide { xsd:string { maxLength = "12" } }
+          | attribute nuclide { xsd:string { maxLength = "12" } } )
+      )
+    )
+  }* &
+
   element tally {
     (element id { xsd:int } | attribute id { xsd:int }) &
     (element name { xsd:string { maxLength="52" } } |
@@ -42,12 +57,7 @@ element tallies {
       (element threshold { xsd:double} | attribute threshold { xsd:double }) &
       (element scores { list { xsd:string { maxLength = "20" }+ } } | attribute scores { list { xsd:string { maxLength = "20"}+ } } )?
     }* &
-    element derivative {
-      (element variable { ( "density" | "nuclide_density") } |
-        attribute variable { ( "density" | "nuclide_density") } ) &
-      (element material { xsd:int } | attribute material { xsd:int }) &
-      (element nuclide { xsd:string } | attribute nuclide { xsd:string })?
-    }?
+    (element derivative { xsd:int } | attribute derivative { xsd:int } )?
   }* &
 
   element assume_separate { xsd:boolean }?

src/relaxng/tallies.rng

@@ -89,6 +89,60 @@
         </interleave>
       </element>
     </zeroOrMore>
+    <zeroOrMore>
+      <element name="derivative">
+        <interleave>
+          <choice>
+            <element name="id">
+              <data type="int"/>
+            </element>
+            <attribute name="id">
+              <data type="int"/>
+            </attribute>
+          </choice>
+          <choice>
+            <element name="material">
+              <data type="int"/>
+            </element>
+            <attribute name="material">
+              <data type="int"/>
+            </attribute>
+          </choice>
+          <choice>
+            <choice>
+              <element name="variable">
+                <value>density</value>
+              </element>
+              <attribute name="variable">
+                <value>density</value>
+              </attribute>
+            </choice>
+            <interleave>
+              <choice>
+                <element name="variable">
+                  <value>nuclide_density</value>
+                </element>
+                <attribute name="variable">
+                  <value>nuclide_density</value>
+                </attribute>
+              </choice>
+              <choice>
+                <element name="nuclide">
+                  <data type="string">
+                    <param name="maxLength">12</param>
+                  </data>
+                </element>
+                <attribute name="nuclide">
+                  <data type="string">
+                    <param name="maxLength">12</param>
+                  </data>
+                </attribute>
+              </choice>
+            </interleave>
+          </choice>
+        </interleave>
+      </element>
+    </zeroOrMore>
     <zeroOrMore>
       <element name="tally">
         <interleave>
@@ -254,6 +308,16 @@
               </interleave>
             </element>
           </zeroOrMore>
+          <optional>
+            <choice>
+              <element name="derivative">
+                <data type="int"/>
+              </element>
+              <attribute name="derivative">
+                <data type="int"/>
+              </attribute>
+            </choice>
+          </optional>
         </interleave>
       </element>
     </zeroOrMore>
@@ -262,39 +326,5 @@
         <data type="boolean"/>
       </element>
     </optional>
-    <optional>
-      <element name="derivative">
-        <choice>
-          <element name="variable">
-            <choice>
-              <value>density</value>
-              <value>nuclide_density</value>
-            </choice>
-          </element>
-          <attribute name="variable">
-            <choice>
-              <value>density</value>
-              <value>nuclide_density</value>
-            </choice>
-          </attribute>
-        </choice>
-        <choice>
-          <element name="material">
-            <data type="int"/>
-          </element>
-          <attribute name="material">
-            <data type="int"/>
-          </attribute>
-        </choice>
-        <optional>
-          <element name="nuclide">
-            <data type="string"/>
-          </element>
-          <attribute name="nuclide">
-            <data type="string"/>
-          </attribute>
-        </optional>
-      </element>
-    </optional>
   </interleave>
 </element>

src/state_point.F90

@@ -203,17 +203,17 @@ contains
                  // trim(to_str(deriv % id)))
             select case (deriv % variable)
             case (DIFF_DENSITY)
-              call write_dataset(deriv_group, "dependent variable", "density")
+              call write_dataset(deriv_group, "independent variable", "density")
               call write_dataset(deriv_group, "material", deriv % diff_material)
             case (DIFF_NUCLIDE_DENSITY)
-              call write_dataset(deriv_group, "dependent variable", &
+              call write_dataset(deriv_group, "independent variable", &
                    "nuclide_density")
               call write_dataset(deriv_group, "material", deriv % diff_material)
               i_list = nuclides(deriv % diff_nuclide) % listing
               call write_dataset(deriv_group, "nuclide", &
                    xs_listings(i_list) % alias)
             case default
-              call fatal_error("Dependent variable for derivative " &
+              call fatal_error("Independent variable for derivative " &
                    // trim(to_str(deriv % id)) // " not defined in &
                    &state_point.F90.")
             end select