add a tutorial

.gitignore

@@ -12,6 +12,8 @@ dask-worker-space
 boxkit/depends/boost/*
 .sphinx/build/*
 .sphinx/source/media/*
+.sphinx/source/tutorials/*
 !.sphinx/source/index.rst
 !./README.rst
 !./DESIGN.rst
+!tutorials/*/*.rst

.sphinx/setup

@@ -5,7 +5,9 @@
 # command
 
 echo Removing artifacts
-rm -rf source/README.rst source/media module.rst boxkit.*
+rm -rf source/README.rst source/media \
+	source/module.rst source/boxkit.* \
+	source/tutorials
 
 sphinx-apidoc -fPeM --implicit-namespaces -o source ../../BoxKit/boxkit \
 	../../BoxKit/boxkit/__meta__.py \
@@ -14,4 +16,9 @@ sphinx-apidoc -fPeM --implicit-namespaces -o source ../../BoxKit/boxkit \
 
 echo Copying README.rst
 cp ../../BoxKit/README.rst source/.
+
+echo Copying media
 cp -r ../../BoxKit/media source/.
+
+echo Copying tutorials
+cp -r ../../BoxKit/tutorials source/.

README.rst

@@ -9,17 +9,19 @@
 **********
  Overview
 **********
-BoxKit is a library that provides building blocks to parallelize and 
+
+BoxKit is a library that provides building blocks to parallelize and
 scale data science, statistical analysis, and machine learning
-applications for block-structured simulation datasets. Spatial data
-from simulations can be accessed and managed using tools available 
-in this library to interface with packages like SciKit, PyTorch, and 
-OpticalFlow for post-processing and analysis.
+applications for block-structured simulation datasets. Spatial data from
+simulations can be accessed and managed using tools available in this
+library to interface with packages like SciKit, PyTorch, and OpticalFlow
+for post-processing and analysis.
 
-The library provides a Python interface to efficiently access Adaptive 
+The library provides a Python interface to efficiently access Adaptive
 Mesh Refinement (AMR) data typical of simulation outputs, and leverages
-multiprocessing libraries like JobLib and Dask to scale analysis on 
-Non-Uniform Memory Access (NUMA) and distributed computing architectures.
+multiprocessing libraries like JobLib and Dask to scale analysis on
+Non-Uniform Memory Access (NUMA) and distributed computing
+architectures.
 
 **************
  Installation
@@ -253,6 +255,16 @@ for an example.
 Please file an issue on the repository page to report bugs, request
 features, and ask questions about usage
 
+***********
+ Tutorials
+***********
+
+.. toctree::
+   :glob:
+
+   tutorials/astrophysics_example_01/*
+   tutorials/pool_boiling_gravity/*
+
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
 

docs/README.html

@@ -17,7 +17,7 @@
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="boxkit package" href="boxkit.html" />
+    <link rel="next" title="Astrophysics Example 1" href="tutorials/astrophysics_example_01/astrophysics_example_01.html" />
     <link rel="prev" title="Welcome to BoxKit’s documentation!" href="index.html" /> 
 </head>
 
@@ -46,6 +46,11 @@
 <li class="toctree-l2"><a class="reference internal" href="#testing">Testing</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#citation">Citation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#help-support">Help &amp; Support</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#tutorials">Tutorials</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="tutorials/astrophysics_example_01/astrophysics_example_01.html">Astrophysics Example 1</a></li>
+<li class="toctree-l3"><a class="reference internal" href="tutorials/pool_boiling_gravity/pool_boiling_gravity.html">Pool Boiling Gravity</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="boxkit.html">boxkit package</a></li>
@@ -83,14 +88,15 @@ <h1><a class="reference internal" href="_images/icon.svg"><img alt="icon" src="_
 <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
 <p>BoxKit is a library that provides building blocks to parallelize and
 scale data science, statistical analysis, and machine learning
-applications for block-structured simulation datasets. Spatial data
-from simulations can be accessed and managed using tools available
-in this library to interface with packages like SciKit, PyTorch, and
-OpticalFlow for post-processing and analysis.</p>
+applications for block-structured simulation datasets. Spatial data from
+simulations can be accessed and managed using tools available in this
+library to interface with packages like SciKit, PyTorch, and OpticalFlow
+for post-processing and analysis.</p>
 <p>The library provides a Python interface to efficiently access Adaptive
 Mesh Refinement (AMR) data typical of simulation outputs, and leverages
 multiprocessing libraries like JobLib and Dask to scale analysis on
-Non-Uniform Memory Access (NUMA) and distributed computing architectures.</p>
+Non-Uniform Memory Access (NUMA) and distributed computing
+architectures.</p>
 </div>
 <div class="section" id="installation">
 <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
@@ -275,14 +281,23 @@ <h2>Help &amp; Support<a class="headerlink" href="#help-support" title="Permalin
 <p>Please file an issue on the repository page to report bugs, request
 features, and ask questions about usage</p>
 </div>
+<div class="section" id="tutorials">
+<h2>Tutorials<a class="headerlink" href="#tutorials" title="Permalink to this headline"></a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/astrophysics_example_01/astrophysics_example_01.html">Astrophysics Example 1</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/pool_boiling_gravity/pool_boiling_gravity.html">Pool Boiling Gravity</a></li>
+</ul>
+</div>
+</div>
 </div>
 
 
            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="index.html" class="btn btn-neutral float-left" title="Welcome to BoxKit’s documentation!" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="boxkit.html" class="btn btn-neutral float-right" title="boxkit package" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="tutorials/astrophysics_example_01/astrophysics_example_01.html" class="btn btn-neutral float-right" title="Astrophysics Example 1" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

docs/_sources/README.rst.txt

@@ -9,17 +9,19 @@
 **********
  Overview
 **********
-BoxKit is a library that provides building blocks to parallelize and 
+
+BoxKit is a library that provides building blocks to parallelize and
 scale data science, statistical analysis, and machine learning
-applications for block-structured simulation datasets. Spatial data
-from simulations can be accessed and managed using tools available 
-in this library to interface with packages like SciKit, PyTorch, and 
-OpticalFlow for post-processing and analysis.
+applications for block-structured simulation datasets. Spatial data from
+simulations can be accessed and managed using tools available in this
+library to interface with packages like SciKit, PyTorch, and OpticalFlow
+for post-processing and analysis.
 
-The library provides a Python interface to efficiently access Adaptive 
+The library provides a Python interface to efficiently access Adaptive
 Mesh Refinement (AMR) data typical of simulation outputs, and leverages
-multiprocessing libraries like JobLib and Dask to scale analysis on 
-Non-Uniform Memory Access (NUMA) and distributed computing architectures.
+multiprocessing libraries like JobLib and Dask to scale analysis on
+Non-Uniform Memory Access (NUMA) and distributed computing
+architectures.
 
 **************
  Installation
@@ -253,6 +255,16 @@ for an example.
 Please file an issue on the repository page to report bugs, request
 features, and ask questions about usage
 
+***********
+ Tutorials
+***********
+
+.. toctree::
+   :glob:
+
+   tutorials/astrophysics_example_01/*
+   tutorials/pool_boiling_gravity/*
+
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
 

docs/_sources/tutorials/astrophysics_example_01/astrophysics_example_01.rst.txt

@@ -0,0 +1,97 @@
+########################
+ Astrophysics Example 1
+########################
+
+In this example we will use BoxKit to work with three dimensional
+astrophysics data. After performing the required installation steps we
+are read to import BoxKit into Python environment
+
+.. code:: ipython3
+
+   import boxkit
+
+Next we read and parse dataset information from a HDF5 file,
+``25m_3d_32km_hdf5_plt_cnt_1000``, that contains Flash-X simulation
+output
+
+.. code:: ipython3
+
+   dset = boxkit.read_dataset("25m_3d_32km_hdf5_plt_cnt_1000", source="flash")
+
+We can probe into the information for this dataset by using a simple
+print statement
+
+.. code:: ipython3
+
+   print(dset)
+
+.. parsed-literal::
+
+   Dataset:
+    - type         : <class 'boxkit.library._dataset.Dataset'>
+    - file         : <HDF5 file "25m_3d_32km_hdf5_plt_cnt_1000" (mode r)>
+    - keys         : ['dens', 'temp', 'velx', 'vely', 'ye  ', 'fe54', 'fe56', 'o16 ', 'si28', 'entr', 'enuc', 'cr48', 'cr56', 'fe52', 'ni56', 'pres', 'c12 ', 's32 ', 'gpot', 'gamc', 'dtbn', 'velz']
+    - dtype    : [<class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>, <class 'h5pickle.Dataset'>]
+    - bound(z-y-x) : [-10000000000.0, 10000000000.0] x [-10000000000.0, 10000000000.0] x [-10000000000.0, 10000000000.0]
+    - shape(z-y-x) : 8 x 8 x 8
+    - guard(z-y-x) : 0 x 0 x 0
+    - nblocks      : 90200
+    - dtype        : {'dens': <class 'h5pickle.Dataset'>, 'temp': <class 'h5pickle.Dataset'>, 'velx': <class 'h5pickle.Dataset'>, 'vely': <class 'h5pickle.Dataset'>, 'ye  ': <class 'h5pickle.Dataset'>, 'fe54': <class 'h5pickle.Dataset'>, 'fe56': <class 'h5pickle.Dataset'>, 'o16 ': <class 'h5pickle.Dataset'>, 'si28': <class 'h5pickle.Dataset'>, 'entr': <class 'h5pickle.Dataset'>, 'enuc': <class 'h5pickle.Dataset'>, 'cr48': <class 'h5pickle.Dataset'>, 'cr56': <class 'h5pickle.Dataset'>, 'fe52': <class 'h5pickle.Dataset'>, 'ni56': <class 'h5pickle.Dataset'>, 'pres': <class 'h5pickle.Dataset'>, 'c12 ': <class 'h5pickle.Dataset'>, 's32 ': <class 'h5pickle.Dataset'>, 'gpot': <class 'h5pickle.Dataset'>, 'gamc': <class 'h5pickle.Dataset'>, 'dtbn': <class 'h5pickle.Dataset'>, 'velz': <class 'h5pickle.Dataset'>}
+
+The dataset contains 90200 blocks each of size 8x8x8, along with
+variables listed in ``keys``. We can now use this dataset to create a
+slice at location ``y = 0.1``
+
+.. code:: ipython3
+
+   yloc = 0.1
+   dset_slice = boxkit.create_slice(dset, ymin=yloc, ymax=yloc)
+
+.. code:: ipython3
+
+   print(dset_slice)
+
+.. parsed-literal::
+
+   Region:
+    - type          : <class 'boxkit.library._slice.Slice'>
+    - bound (z-y-x) : [-10000000000.0, 10000000000.0] x [0.0, 1666666624.0] x [-10000000000.0, 10000000000.0]
+
+Now we can loop over blocks in this slice and extract data from right
+indices
+
+.. code:: ipython3
+
+   # import required libraries
+   import numpy
+   import matplotlib.pyplot as pyplot
+
+   # create a pyplot figure object
+   pyplot.figure()
+
+   # Name of the contour variable
+   cvar = "temp"
+
+   # Initialize min/max values
+   min_cval = 1e10
+   max_cval = -1e10
+
+   # loop over blocks for blocklist included in the slice
+   for block in dset_slice.blocklist:
+
+       # Get y-index closest to the probe location
+       yindex = (numpy.abs(block.yrange("center") - yloc)).argmin()
+
+       # Create a mesh grid in x-z plane
+       xmesh, zmesh = numpy.meshgrid(block.xrange("center"), block.yrange("center"))
+
+       # plot contour
+       pyplot.contourf(xmesh,zmesh,block[cvar][:,yindex,:])
+
+       min_cval = min(numpy.min(block[cvar][:,yindex,:]), min_cval)
+       max_cval = max(numpy.max(block[cvar][:,yindex,:]), max_cval)
+
+   #pyplot.colorbar()
+   #pyplot.clim(min_cval,max_cval)
+
+.. image:: output_10_0.png