tboudreaux/GridFire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docs): rebuilt

Browse Source
This commit is contained in:
Emily Boudreaux
2025-07-31 10:54:31 -04:00
parent 2aaeb6440e
commit 63265a2dc3
271 changed files with 5003 additions and 5941 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/html/namespacegridfire.html
View File

@@ -298,8 +298,6 @@ Variables</h2></td></tr>
<p>Alias for CppAD AD type for double precision. </p>
<p>This alias simplifies the use of the CppAD automatic differentiation type. </p>
<p class="definition">Definition at line <a class="el" href="engine__graph_8h_source.html#l00044">44</a> of file <a class="el" href="engine__graph_8h_source.html">engine_graph.h</a>.</p>
</div>
</div>
<a id="a3b1f70dc7ff5b501809330a97079e4f6" name="a3b1f70dc7ff5b501809330a97079e4f6"></a>
@@ -318,8 +316,6 @@ Variables</h2></td></tr>
<dl class="section pre"><dt>Precondition</dt><dd>If using the integer alternative, the value must be &gt;= 0 or -1 to indicate a full build. </dd></dl>
<dl class="section post"><dt>Postcondition</dt><dd>The network builder will interpret and apply the specified depth to control reaction expansion. </dd></dl>
<p class="definition">Definition at line <a class="el" href="building_8h_source.html#l00037">37</a> of file <a class="el" href="building_8h_source.html">building.h</a>.</p>
</div>
</div>
<a id="aa86f08712565f278adacc7cd2361eb31" name="aa86f08712565f278adacc7cd2361eb31"></a>
@@ -336,8 +332,6 @@ Variables</h2></td></tr>
<p>A set of logical reactions. </p>
<p class="definition">Definition at line <a class="el" href="reaction_8h_source.html#l00563">563</a> of file <a class="el" href="reaction_8h_source.html">reaction.h</a>.</p>
</div>
</div>
<a id="ad838ce3fb6cc02c3fd90b924a0dd91b1" name="ad838ce3fb6cc02c3fd90b924a0dd91b1"></a>
@@ -354,8 +348,6 @@ Variables</h2></td></tr>
<p>A set of reactions, typically from a single source like REACLIB. </p>
<p class="definition">Definition at line <a class="el" href="reaction_8h_source.html#l00562">562</a> of file <a class="el" href="reaction_8h_source.html">reaction.h</a>.</p>
</div>
</div>
<a id="a898dfe22579e649935645cbd6f073178" name="a898dfe22579e649935645cbd6f073178"></a>
@@ -370,8 +362,6 @@ Variables</h2></td></tr>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="engine__abstract_8h_source.html#l00065">65</a> of file <a class="el" href="engine__abstract_8h_source.html">engine_abstract.h</a>.</p>
</div>
</div>
<h2 class="groupheader">Enumeration Type Documentation</h2>
@@ -414,8 +404,6 @@ Variables</h2></td></tr>
<tr><td class="fieldname"><a id="a0210bd2e07538932135a56b62b8ddb57a5105376c2b90747e00bed5bf2953dd56" name="a0210bd2e07538932135a56b62b8ddb57a5105376c2b90747e00bed5bf2953dd56"></a>FifthOrder&#160;</td><td class="fielddoc"></td></tr>
</table>
<p class="definition">Definition at line <a class="el" href="building_8h_source.html#l00021">21</a> of file <a class="el" href="building_8h_source.html">building.h</a>.</p>
</div>
</div>
<a id="a3f3d6b3f9742b70e62049ccefbb60f37" name="a3f3d6b3f9742b70e62049ccefbb60f37"></a>
@@ -437,8 +425,6 @@ Variables</h2></td></tr>
<tr><td class="fieldname"><a id="a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2" name="a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2"></a>UNKNOWN&#160;</td><td class="fielddoc"></td></tr>
</table>
<p class="definition">Definition at line <a class="el" href="network_8h_source.html#l00041">41</a> of file <a class="el" href="network_8h_source.html">network.h</a>.</p>
</div>
</div>
<a id="a8bea3d74f35d640e693fa398e9b3e154" name="a8bea3d74f35d640e693fa398e9b3e154"></a>
@@ -482,8 +468,6 @@ Variables</h2></td></tr>
<tr><td class="fieldname"><a id="a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e" name="a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e"></a>BASE_NETWORK_TOO_SHALLOW&#160;</td><td class="fielddoc"></td></tr>
</table>
<p class="definition">Definition at line <a class="el" href="reporting_8h_source.html#l00031">31</a> of file <a class="el" href="reporting_8h_source.html">reporting.h</a>.</p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
@@ -511,8 +495,6 @@ Variables</h2></td></tr>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="construction_8cpp_source.html#l00024">24</a> of file <a class="el" href="construction_8cpp_source.html">construction.cpp</a>.</p>
</div>
</div>
<a id="aedddb89e400a6111f69bfe0c3fd4214e" name="aedddb89e400a6111f69bfe0c3fd4214e"></a>
@@ -614,8 +596,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<dl class="section post"><dt>Postcondition</dt><dd>Returned creation rate is non-negative. </dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Sum of stoichiometry-weighted creation flows for the species. </dd></dl>
<p class="definition">Definition at line <a class="el" href="priming_8cpp_source.html#l00213">213</a> of file <a class="el" href="priming_8cpp_source.html">priming.cpp</a>.</p>
</div>
</div>
<a id="a8f26d5f5fabb42e88261e42bc060cea2" name="a8f26d5f5fabb42e88261e42bc060cea2"></a>
@@ -668,8 +648,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<dl class="section post"><dt>Postcondition</dt><dd>Returned rate constant is non-negative. </dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Sum of absolute stoichiometry-weighted destruction flows for the species. </dd></dl>
<p class="definition">Definition at line <a class="el" href="priming_8cpp_source.html#l00193">193</a> of file <a class="el" href="priming_8cpp_source.html">priming.cpp</a>.</p>
</div>
</div>
<a id="aefc63ddbfe97dcb4178c94dfd1c4b256" name="aefc63ddbfe97dcb4178c94dfd1c4b256"></a>
@@ -706,8 +684,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="priming_8cpp_source.html#l00017">17</a> of file <a class="el" href="priming_8cpp_source.html">priming.cpp</a>.</p>
</div>
</div>
<a id="acd0bfdfbce4e84af102d62ff8a797c9f" name="acd0bfdfbce4e84af102d62ff8a797c9f"></a>
@@ -743,8 +719,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<dl class="section post"><dt>Postcondition</dt><dd>engine.networkReactions restored to its initial state; returned report contains primedComposition, massFractionChanges for each species, success flag, and status code. </dd></dl>
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="structgridfire_1_1_priming_report.html" title="Captures the result of a network priming operation.">PrimingReport</a> encapsulating the results of the priming operation. </dd></dl>
<p class="definition">Definition at line <a class="el" href="priming_8cpp_source.html#l00039">39</a> of file <a class="el" href="priming_8cpp_source.html">priming.cpp</a>.</p>
</div>
</div>
<a id="a8b245f261cd8d1711ae8d593b054cf98" name="a8b245f261cd8d1711ae8d593b054cf98"></a>
@@ -762,8 +736,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="network_8cpp_source.html#l00065">65</a> of file <a class="el" href="network_8cpp_source.html">network.cpp</a>.</p>
</div>
</div>
<h2 class="groupheader">Variable Documentation</h2>
@@ -791,12 +763,10 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<div class="line"> {<a class="code hl_enumvalue" href="#a3f3d6b3f9742b70e62049ccefbb60f37a9b8db7b445ae4f1bd114caa42a583182">REACLIB</a>, <span class="stringliteral">&quot;REACLIB&quot;</span>},</div>
<div class="line"> {<a class="code hl_enumvalue" href="#a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2">UNKNOWN</a>, <span class="stringliteral">&quot;Unknown&quot;</span>}</div>
<div class="line"> }</div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37a1fc7adf719c40457abfdb8334675faea"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37a1fc7adf719c40457abfdb8334675faea">gridfire::APPROX8</a></div><div class="ttdeci">@ APPROX8</div><div class="ttdoc">Approx8 nuclear reaction network format.</div><div class="ttdef"><b>Definition</b> <a href="network_8h_source.html#l00042">network.h:42</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37a9b8db7b445ae4f1bd114caa42a583182"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37a9b8db7b445ae4f1bd114caa42a583182">gridfire::REACLIB</a></div><div class="ttdeci">@ REACLIB</div><div class="ttdoc">General REACLIB nuclear reaction network format.</div><div class="ttdef"><b>Definition</b> <a href="network_8h_source.html#l00043">network.h:43</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2">gridfire::UNKNOWN</a></div><div class="ttdeci">@ UNKNOWN</div><div class="ttdef"><b>Definition</b> <a href="network_8h_source.html#l00044">network.h:44</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37a1fc7adf719c40457abfdb8334675faea"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37a1fc7adf719c40457abfdb8334675faea">gridfire::APPROX8</a></div><div class="ttdeci">@ APPROX8</div><div class="ttdoc">Approx8 nuclear reaction network format.</div><div class="ttdef"><b>Definition</b> network.h:42</div></div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37a9b8db7b445ae4f1bd114caa42a583182"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37a9b8db7b445ae4f1bd114caa42a583182">gridfire::REACLIB</a></div><div class="ttdeci">@ REACLIB</div><div class="ttdoc">General REACLIB nuclear reaction network format.</div><div class="ttdef"><b>Definition</b> network.h:43</div></div>
<div class="ttc" id="anamespacegridfire_html_a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2"><div class="ttname"><a href="#a3f3d6b3f9742b70e62049ccefbb60f37aac700abde5f6ff8b7328193eb19697b2">gridfire::UNKNOWN</a></div><div class="ttdeci">@ UNKNOWN</div><div class="ttdef"><b>Definition</b> network.h:44</div></div>
</div><!-- fragment -->
<p class="definition">Definition at line <a class="el" href="network_8h_source.html#l00047">47</a> of file <a class="el" href="network_8h_source.html">network.h</a>.</p>
</div>
</div>
<a id="a96c062f94713921e5d7568ecedcdcb06" name="a96c062f94713921e5d7568ecedcdcb06"></a>
@@ -822,8 +792,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<p>Minimum abundance threshold below which species are ignored. </p>
<p>Species with abundances below this threshold are treated as zero in reaction rate calculations. This helps to improve performance by avoiding unnecessary calculations for trace species. </p>
<p class="definition">Definition at line <a class="el" href="engine__graph_8h_source.html#l00066">66</a> of file <a class="el" href="engine__graph_8h_source.html">engine_graph.h</a>.</p>
</div>
</div>
<a id="ada3c137c014ecd8d06200fea2d1a9f50" name="ada3c137c014ecd8d06200fea2d1a9f50"></a>
@@ -849,8 +817,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<p>Minimum density threshold below which reactions are ignored. </p>
<p>Reactions are not calculated if the density falls below this threshold. This helps to improve performance by avoiding unnecessary calculations in very low-density regimes. </p>
<p class="definition">Definition at line <a class="el" href="engine__graph_8h_source.html#l00057">57</a> of file <a class="el" href="engine__graph_8h_source.html">engine_graph.h</a>.</p>
</div>
</div>
<a id="ae01b1738df1921db565bcbd68dd6cf64" name="ae01b1738df1921db565bcbd68dd6cf64"></a>
@@ -876,8 +842,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<p>Minimum value for Jacobian matrix entries. </p>
<p>Jacobian matrix entries with absolute values below this threshold are treated as zero to maintain sparsity and improve performance. </p>
<p class="definition">Definition at line <a class="el" href="engine__graph_8h_source.html#l00074">74</a> of file <a class="el" href="engine__graph_8h_source.html">engine_graph.h</a>.</p>
</div>
</div>
<a id="a02be158966bf82a91b159b7a962c3fa5" name="a02be158966bf82a91b159b7a962c3fa5"></a>
@@ -908,19 +872,17 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
<div class="line"> {<a class="code hl_enumvalue" href="#a8bea3d74f35d640e693fa398e9b3e154a186367e42446c004076290ca7913d931">PrimingReportStatus::FAILED_TO_FIND_PRIMING_REACTIONS</a>, <span class="stringliteral">&quot;Failed to Find Priming Reactions&quot;</span>},</div>
<div class="line"> {<a class="code hl_enumvalue" href="#a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e">PrimingReportStatus::BASE_NETWORK_TOO_SHALLOW</a>, <span class="stringliteral">&quot;Base Network Too Shallow&quot;</span>}</div>
<div class="line"> }</div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a186367e42446c004076290ca7913d931"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a186367e42446c004076290ca7913d931">gridfire::PrimingReportStatus::FAILED_TO_FIND_PRIMING_REACTIONS</a></div><div class="ttdeci">@ FAILED_TO_FIND_PRIMING_REACTIONS</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00037">reporting.h:37</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a5afaf45bc4c02208d502d9c0c26d8287"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a5afaf45bc4c02208d502d9c0c26d8287">gridfire::PrimingReportStatus::MAX_ITERATIONS_REACHED</a></div><div class="ttdeci">@ MAX_ITERATIONS_REACHED</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00034">reporting.h:34</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a64d98633bac1de0eb2a539cbfd2a5c2a"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a64d98633bac1de0eb2a539cbfd2a5c2a">gridfire::PrimingReportStatus::FULL_SUCCESS</a></div><div class="ttdeci">@ FULL_SUCCESS</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00032">reporting.h:32</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a708c14ec56942aa5f32e7bef1e29db45"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a708c14ec56942aa5f32e7bef1e29db45">gridfire::PrimingReportStatus::NO_SPECIES_TO_PRIME</a></div><div class="ttdeci">@ NO_SPECIES_TO_PRIME</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00033">reporting.h:33</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a9870268bdece09274aea75557a19158a"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a9870268bdece09274aea75557a19158a">gridfire::PrimingReportStatus::FAILED_TO_FIND_CREATION_CHANNEL</a></div><div class="ttdeci">@ FAILED_TO_FIND_CREATION_CHANNEL</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00036">reporting.h:36</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e">gridfire::PrimingReportStatus::BASE_NETWORK_TOO_SHALLOW</a></div><div class="ttdeci">@ BASE_NETWORK_TOO_SHALLOW</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00038">reporting.h:38</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154ae8870a753743b62c511c939eef95c93f"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154ae8870a753743b62c511c939eef95c93f">gridfire::PrimingReportStatus::FAILED_TO_FINALIZE_COMPOSITION</a></div><div class="ttdeci">@ FAILED_TO_FINALIZE_COMPOSITION</div><div class="ttdef"><b>Definition</b> <a href="reporting_8h_source.html#l00035">reporting.h:35</a></div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a186367e42446c004076290ca7913d931"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a186367e42446c004076290ca7913d931">gridfire::PrimingReportStatus::FAILED_TO_FIND_PRIMING_REACTIONS</a></div><div class="ttdeci">@ FAILED_TO_FIND_PRIMING_REACTIONS</div><div class="ttdef"><b>Definition</b> reporting.h:37</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a5afaf45bc4c02208d502d9c0c26d8287"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a5afaf45bc4c02208d502d9c0c26d8287">gridfire::PrimingReportStatus::MAX_ITERATIONS_REACHED</a></div><div class="ttdeci">@ MAX_ITERATIONS_REACHED</div><div class="ttdef"><b>Definition</b> reporting.h:34</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a64d98633bac1de0eb2a539cbfd2a5c2a"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a64d98633bac1de0eb2a539cbfd2a5c2a">gridfire::PrimingReportStatus::FULL_SUCCESS</a></div><div class="ttdeci">@ FULL_SUCCESS</div><div class="ttdef"><b>Definition</b> reporting.h:32</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a708c14ec56942aa5f32e7bef1e29db45"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a708c14ec56942aa5f32e7bef1e29db45">gridfire::PrimingReportStatus::NO_SPECIES_TO_PRIME</a></div><div class="ttdeci">@ NO_SPECIES_TO_PRIME</div><div class="ttdef"><b>Definition</b> reporting.h:33</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154a9870268bdece09274aea75557a19158a"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154a9870268bdece09274aea75557a19158a">gridfire::PrimingReportStatus::FAILED_TO_FIND_CREATION_CHANNEL</a></div><div class="ttdeci">@ FAILED_TO_FIND_CREATION_CHANNEL</div><div class="ttdef"><b>Definition</b> reporting.h:36</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154ab837953f2841baabbae6bb5f2e43e71e">gridfire::PrimingReportStatus::BASE_NETWORK_TOO_SHALLOW</a></div><div class="ttdeci">@ BASE_NETWORK_TOO_SHALLOW</div><div class="ttdef"><b>Definition</b> reporting.h:38</div></div>
<div class="ttc" id="anamespacegridfire_html_a8bea3d74f35d640e693fa398e9b3e154ae8870a753743b62c511c939eef95c93f"><div class="ttname"><a href="#a8bea3d74f35d640e693fa398e9b3e154ae8870a753743b62c511c939eef95c93f">gridfire::PrimingReportStatus::FAILED_TO_FINALIZE_COMPOSITION</a></div><div class="ttdeci">@ FAILED_TO_FINALIZE_COMPOSITION</div><div class="ttdef"><b>Definition</b> reporting.h:35</div></div>
</div><!-- fragment -->
<p>Mapping from <a class="el" href="#a8bea3d74f35d640e693fa398e9b3e154" title="Enumerates outcome codes for a network priming operation.">PrimingReportStatus</a> codes to human-readable strings. </p>
<p>Used when formatting or logging the priming status. No preconditions. The map contains entries for all <a class="el" href="#a8bea3d74f35d640e693fa398e9b3e154" title="Enumerates outcome codes for a network priming operation.">PrimingReportStatus</a> values. </p>
<p class="definition">Definition at line <a class="el" href="reporting_8h_source.html#l00047">47</a> of file <a class="el" href="reporting_8h_source.html">reporting.h</a>.</p>
</div>
</div>
<a id="a8b632637f62614f509cde0e404a79054" name="a8b632637f62614f509cde0e404a79054"></a>
@@ -943,8 +905,6 @@ Resolved integer depth from maxLayers must not be zero. </dd></dl>
</table>
</div><div class="memdoc">
<p class="definition">Definition at line <a class="el" href="engine__multiscale_8cpp_source.html#l00150">150</a> of file <a class="el" href="engine__multiscale_8cpp_source.html">engine_multiscale.cpp</a>.</p>
</div>
</div>
</div><!-- contents -->