274 lines
16 KiB
HTML
274 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
||
<meta name="generator" content="Doxygen 1.13.2"/>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
<title>GridFire: GridFire Python Usage Guide</title>
|
||
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="jquery.js"></script>
|
||
<script type="text/javascript" src="dynsections.js"></script>
|
||
<script type="text/javascript" src="clipboard.js"></script>
|
||
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="navtreedata.js"></script>
|
||
<script type="text/javascript" src="navtree.js"></script>
|
||
<script type="text/javascript" src="resize.js"></script>
|
||
<script type="text/javascript" src="cookie.js"></script>
|
||
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
<script type="text/javascript" src="search/search.js"></script>
|
||
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
||
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
|
||
</head>
|
||
<body>
|
||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
<div id="titlearea">
|
||
<table cellspacing="0" cellpadding="0">
|
||
<tbody>
|
||
<tr id="projectrow">
|
||
<td id="projectalign">
|
||
<div id="projectname">GridFire<span id="projectnumber"> 0.6.0</span>
|
||
</div>
|
||
<div id="projectbrief">General Purpose Nuclear Network</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.13.2 -->
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
||
/* @license-end */
|
||
</script>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function() { codefold.init(0); });
|
||
/* @license-end */
|
||
</script>
|
||
<script type="text/javascript" src="menudata.js"></script>
|
||
<script type="text/javascript" src="menu.js"></script>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function() {
|
||
initMenu('',true,false,'search.php','Search',true);
|
||
$(function() { init_search(); });
|
||
});
|
||
/* @license-end */
|
||
</script>
|
||
<div id="main-nav"></div>
|
||
</div><!-- top -->
|
||
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
<div id="nav-tree">
|
||
<div id="nav-tree-contents">
|
||
<div id="nav-sync" class="sync"></div>
|
||
</div>
|
||
</div>
|
||
<div id="splitbar" style="-moz-user-select:none;"
|
||
class="ui-resizable-handle">
|
||
</div>
|
||
</div>
|
||
<script type="text/javascript">
|
||
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
||
$(function(){initNavTree('md_docs_2static_2usage.html',''); initResizable(true); });
|
||
/* @license-end */
|
||
</script>
|
||
<div id="doc-content">
|
||
<!-- window showing the filter options -->
|
||
<div id="MSearchSelectWindow"
|
||
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
</div>
|
||
|
||
<!-- iframe showing the search results (closed by default) -->
|
||
<div id="MSearchResultsWindow">
|
||
<div id="MSearchResults">
|
||
<div class="SRPage">
|
||
<div id="SRIndex">
|
||
<div id="SRResults"></div>
|
||
<div class="SRStatus" id="Loading">Loading...</div>
|
||
<div class="SRStatus" id="Searching">Searching...</div>
|
||
<div class="SRStatus" id="NoMatches">No Matches</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div><div class="header">
|
||
<div class="headertitle"><div class="title">GridFire Python Usage Guide</div></div>
|
||
</div><!--header-->
|
||
<div class="contents">
|
||
<div class="textblock"><p><a class="anchor" id="autotoc_md57"></a></p>
|
||
<p>This tutorial walks you through installing GridFire’s Python bindings, choosing engines and views thoughtfully, running a simulation, and visualizing your results.</p>
|
||
<hr />
|
||
<h1><a class="anchor" id="autotoc_md59"></a>
|
||
1. Installation</h1>
|
||
<h2><a class="anchor" id="autotoc_md60"></a>
|
||
1.1 PyPI Release</h2>
|
||
<p>The quickest way to get started is: </p><div class="fragment"><div class="line">pip install gridfire</div>
|
||
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md61"></a>
|
||
1.2 Development from Source</h2>
|
||
<p>If you want the cutting-edge features or need to hack the C++ backend: </p><div class="fragment"><div class="line">git clone https://github.com/4DSTAR/GridFire.git</div>
|
||
<div class="line">cd GridFire</div>
|
||
<div class="line"># Create a virtualenv to isolate dependencies</div>
|
||
<div class="line">python3 -m venv .venv && source .venv/bin/activate</div>
|
||
<div class="line"> </div>
|
||
<div class="line"># Install Python bindings (meson-python & pybind11 under the hood)</div>
|
||
<div class="line">pip install .</div>
|
||
</div><!-- fragment --><p>You can also build manually with Meson (generally end users will not need to do this): </p><div class="fragment"><div class="line">meson setup build-python</div>
|
||
<div class="line">meson compile -C build_gridfire</div>
|
||
</div><!-- fragment --><hr />
|
||
<h1><a class="anchor" id="autotoc_md63"></a>
|
||
2. Why These Engines and Views?</h1>
|
||
<p>GridFire’s design balances physical fidelity and performance. Here’s why we pick each component:</p>
|
||
<ol type="1">
|
||
<li><b>GraphEngine</b>: Constructs the <b>full</b> reaction network from Reaclib rates and composition. Use this when:<ul>
|
||
<li>You need maximum physical accuracy (no reactions are omitted). <br />
|
||
</li>
|
||
<li>You are exploring new burning pathways or validating against literature. <br />
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>MultiscalePartitioningEngineView</b>: Implements the Hix & Thielemann partitioning strategy:<ul>
|
||
<li><b>Fast reactions</b> vs <b>slow reactions</b> are split onto separate kernels. <br />
|
||
</li>
|
||
<li>This reduces stiffness by isolating processes on very different timescales. <br />
|
||
</li>
|
||
<li>Choose when your network spans orders of magnitude in timescales (e.g., rapid proton captures vs. slow beta decays). <br />
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>AdaptiveEngineView</b>: Dynamically culls low-flow reactions at runtime:<ul>
|
||
<li>At each timestep, reactions with negligible contribution are temporarily removed. <br />
|
||
</li>
|
||
<li>This greatly accelerates large networks without significant loss of accuracy. <br />
|
||
</li>
|
||
<li>Ideal for long integrations where the active set evolves over time. <br />
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><b>Leading-Edge Views</b>: <br />
|
||
<ul>
|
||
<li><code>NetworkPrimingEngineView</code> to inject seed species and study ignition phenomena. <br />
|
||
</li>
|
||
<li><code>DefinedEngineView</code> to freeze the network to a user-specified subset (e.g., focus on the CNO cycle). <br />
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
<p>By composing these views in sequence, you can tailor accuracy vs performance for your scientific question. Commonly one might use a flow like <b>GraphEngine → Partitioning → Adaptive</b> to capture both full-network physics and manageable stiffness.</p>
|
||
<hr />
|
||
<h1><a class="anchor" id="autotoc_md65"></a>
|
||
3. Step-by-Step Example</h1>
|
||
<p>Adapted from <a href="../../tests/python/test.py"><code>tests/python/test.py</code></a>. Comments explain each choice.</p>
|
||
<div class="fragment"><div class="line"><span class="keyword">import</span> matplotlib.pyplot <span class="keyword">as</span> plt</div>
|
||
<div class="line"><span class="keyword">from</span> gridfire.engine <span class="keyword">import</span> GraphEngine, MultiscalePartitioningEngineView, AdaptiveEngineView</div>
|
||
<div class="line"><span class="keyword">from</span> <a class="code hl_namespace" href="namespacegridfire_1_1solver.html">gridfire.solver</a> <span class="keyword">import</span> DirectNetworkSolver</div>
|
||
<div class="line"><span class="keyword">from</span> gridfire.type <span class="keyword">import</span> NetIn</div>
|
||
<div class="line"><span class="keyword">from</span> fourdst.composition <span class="keyword">import</span> Composition</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 1. Define your composition (e.g., M-dwarf surface mix)</span></div>
|
||
<div class="line">symbols = [<span class="stringliteral">"H-1"</span>,<span class="stringliteral">"He-3"</span>,<span class="stringliteral">"He-4"</span>,<span class="stringliteral">"C-12"</span>,<span class="stringliteral">"N-14"</span>,<span class="stringliteral">"O-16"</span>,<span class="stringliteral">"Ne-20"</span>,<span class="stringliteral">"Mg-24"</span>]</div>
|
||
<div class="line">abundances = [0.708,2.94e-5,0.276,0.003,0.0011,9.62e-3,1.62e-3,5.16e-4]</div>
|
||
<div class="line">comp = Composition()</div>
|
||
<div class="line">comp.registerSymbols(symbols)</div>
|
||
<div class="line">comp.setMassFraction(symbols, abundances)</div>
|
||
<div class="line">comp.finalize(normalize=<span class="keyword">True</span>) <span class="comment"># scale to total mass = 1</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 2. Prepare the NetIn object</span></div>
|
||
<div class="line">netIn = NetIn()</div>
|
||
<div class="line">netIn.composition = comp</div>
|
||
<div class="line">netIn.temperature = 1.5e7 <span class="comment"># Kelvin</span></div>
|
||
<div class="line">netIn.density = 1.6e2 <span class="comment"># g/cm³</span></div>
|
||
<div class="line">netIn.tMax = 3.15e7 <span class="comment"># seconds to evolve (~1yr)</span></div>
|
||
<div class="line">netIn.dt0 = 1e-12 <span class="comment"># initial timestep</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 3. Construct the full network engine</span></div>
|
||
<div class="line">build_depth = 2 <span class="comment"># shallow test network for speed; Full = -1</span></div>
|
||
<div class="line">baseEngine = GraphEngine(comp, buildDepth=build_depth)</div>
|
||
<div class="line">baseEngine.setUseReverseReactions(<span class="keyword">False</span>) <span class="comment"># At these temps we can turn off reverse reactions</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 4. Partition fast/slow reactions (reduces stiffness)</span></div>
|
||
<div class="line">partitionedEngine = MultiscalePartitioningEngineView(baseEngine)</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 5. Adaptively cull negligible flows (improves speed)</span></div>
|
||
<div class="line">adaptiveEngine = AdaptiveEngineView(partitionedEngine)</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 6. Choose an ODE solver (implicit Rosenbrock4)</span></div>
|
||
<div class="line">solver = DirectNetworkSolver(adaptiveEngine, absTol=1e-12, relTol=1e-8)</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 7. Run the integration</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line">netOut = solver.evaluate(netIn)</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># 8. Final result:</span></div>
|
||
<div class="line">print(f<span class="stringliteral">"Final H-1 fraction: {netOut.composition.getMassFraction('H-1')}"</span>)</div>
|
||
<div class="ttc" id="anamespacegridfire_1_1solver_html"><div class="ttname"><a href="namespacegridfire_1_1solver.html">gridfire::solver</a></div><div class="ttdef"><b>Definition</b> solver.h:18</div></div>
|
||
</div><!-- fragment --><p><b>Why these choices?</b> <br />
|
||
</p><ul>
|
||
<li><b>buildDepth=2</b>: In Emily’s preliminary tests, depth=2 captures key reaction loops without the overhead of a full network. <br />
|
||
</li>
|
||
<li><b>Partition & Adaptive Views</b>: Partitioning reduces stiffness between rapid charged-particle captures and slower β-decays; adaptive culling keeps the working set minimal. <br />
|
||
</li>
|
||
<li><b>Implicit solver</b>: Rosenbrock4 handles stiff systems robustly, letting you push to longer <code>tMax</code>.</li>
|
||
</ul>
|
||
<hr />
|
||
<h1><a class="anchor" id="autotoc_md67"></a>
|
||
4. Visualizing Reaction Networks</h1>
|
||
<p>GridFire engines and views provide built-in export methods for Graphviz DOT and CSV formats:</p>
|
||
<div class="fragment"><div class="line"><span class="comment"># Export the base network to DOT for Graphviz</span></div>
|
||
<div class="line">baseEngine.exportToDot(<span class="stringliteral">'network.dot'</span>)</div>
|
||
<div class="line"><span class="comment"># Optionally generate a PNG (shell):</span></div>
|
||
<div class="line"><span class="comment"># dot -Tpng network.dot -o network.png</span></div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># Export a partitioned view of the network</span></div>
|
||
<div class="line">partitionedEngine.exportToDot(<span class="stringliteral">'partitioned.dot'</span>)</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># Export to CSV for programmatic analysis</span></div>
|
||
<div class="line">baseEngine.exportToCSV(<span class="stringliteral">'network.csv'</span>)</div>
|
||
</div><!-- fragment --><p> You can then use tools like Graphviz or pandas: </p><div class="fragment"><div class="line"># Convert DOT to PNG</div>
|
||
<div class="line">dot -Tpng network.dot -o network.png</div>
|
||
</div><!-- fragment --> <div class="fragment"><div class="line"><span class="keyword">import</span> pandas <span class="keyword">as</span> pd</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># Load and inspect reaction list</span></div>
|
||
<div class="line">df = pd.read_csv(<span class="stringliteral">'network.csv'</span>)</div>
|
||
<div class="line">print(df.head())</div>
|
||
</div><!-- fragment --><p> For time-series data, record intermediates with an observer and save with pandas or numpy: </p><div class="fragment"><div class="line"><span class="keyword">import</span> pandas <span class="keyword">as</span> pd</div>
|
||
<div class="line"> </div>
|
||
<div class="line"><span class="comment"># Build a DataFrame of time vs species fraction</span></div>
|
||
<div class="line">df = pd.DataFrame({<span class="stringliteral">'time'</span>: t, <span class="stringliteral">'H-1'</span>: X_H1})</div>
|
||
<div class="line">df.to_csv(<span class="stringliteral">'H1_evolution.csv'</span>, index=<span class="keyword">False</span>)</div>
|
||
</div><!-- fragment --><p> Then plot in pandas or Excel for custom figures.</p>
|
||
<hr />
|
||
<h1><a class="anchor" id="autotoc_md69"></a>
|
||
5. Beyond the Basics</h1>
|
||
<ul>
|
||
<li><b>Custom Partition Functions</b>: In Python, subclass <code><a class="el" href="classgridfire_1_1partition_1_1_partition_function.html" title="Abstract interface for evaluating nuclear partition functions.">gridfire.partition.PartitionFunction</a></code>, override <code>evaluate</code>, <code>supports</code>, and <code>clone</code> to implement new weighting schemes. <br />
|
||
</li>
|
||
<li><b>Parameter Studies</b>: Loop over <code>buildDepth</code>, solver tolerances, or initial compositions to get a sense of the sensitity of the network to input conditions or build a monte carlo grid. <br />
|
||
</li>
|
||
<li><b>Error Handling</b>: <div class="fragment"><div class="line"><span class="keywordflow">try</span>:</div>
|
||
<div class="line"> results = solver.evaluate(netIn)</div>
|
||
<div class="line"><span class="keywordflow">except</span> GridFireRuntimeError <span class="keyword">as</span> e:</div>
|
||
<div class="line"> print(<span class="stringliteral">'Fatal engine error:'</span>, e)</div>
|
||
<div class="line"><span class="keywordflow">except</span> GridFireValueError <span class="keyword">as</span> e:</div>
|
||
<div class="line"> print(<span class="stringliteral">'Invalid input:'</span>, e)</div>
|
||
</div><!-- fragment --></li>
|
||
</ul>
|
||
<p>For full API details, consult the docstrings in <code>src/python/</code> and the C++ implementation in <code>src/lib/</code>. Enjoy exploring nuclear astrophysics with GridFire! </p>
|
||
</div></div><!-- contents -->
|
||
</div><!-- PageDoc -->
|
||
</div><!-- doc-content -->
|
||
<!-- start footer part -->
|
||
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
<ul>
|
||
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|