docs updates for 0.3.0 (#210)

* docs updates for 0.3.0

* enh package helper script, add fix for git_archive_all for windows

package.py

@@ -57,22 +57,28 @@
 
 from os.path import join as pjoin
 
-def create_package(output_file=None):
+def create_package(output_file,version):
     scripts_dir = pjoin(os.path.abspath(os.path.split(__file__)[0]),"scripts")
     pkg_script = pjoin(scripts_dir,"git_archive_all.py");
     repo_name = os.path.basename(os.path.dirname(os.path.abspath(__file__)))
     if output_file is None:
          suffix = "tar"
          t = datetime.datetime.now()
          output_file = "%s.%04d.%02d.%02d.%s" % (repo_name,t.year,t.month,t.day,suffix)
-    cmd = "python " + pkg_script + " --prefix=conduit " + output_file
+    cmd = "python " + pkg_script + " --prefix=conduit" 
+    if not version is None:
+        cmd += "-" + version
+    cmd +=  " " + output_file
     print "[exe: %s]" % cmd
     subprocess.call(cmd,shell=True)
 
 if __name__ == "__main__":
-    ofile  = None
+    ofile   = None
+    version = None
     if len(sys.argv) > 1:
-        ofile  = sys.argv[1]
-    create_package(ofile)
+        ofile = sys.argv[1]
+    if len(sys.argv) > 2:
+        version = sys.argv[2]
+    create_package(ofile,version)
 
 

scripts/git_archive_all.py

@@ -27,7 +27,23 @@
 from __future__ import unicode_literals
 
 import logging
-from os import extsep, path, readlink, curdir
+
+########################################
+# 2017-09-09 cyrush: 
+# fix for readlink issue on windows
+########################################
+# old:
+#from os import extsep, path, readlink, curdir
+# new:
+from os import extsep, path, curdir
+import platform
+if platform.system() != "Windows":
+    from os import readlink
+else:
+    def readlink(path):
+        return path
+########################################
+
 from subprocess import CalledProcessError, Popen, PIPE
 import sys
 import tarfile
@@ -36,7 +52,6 @@
 
 __version__ = "1.16.4"
 
-
 class GitArchiver(object):
     """
     GitArchiver

src/docs/sphinx/blueprint_mesh.rst

@@ -257,6 +257,19 @@ specified using a single shape topology for each element shape.
    Future version of the mesh blueprint will expand support to include mixed elements types in a single array with related
    index arrays.
 
+
+Element Windings
+^^^^^^^^^^^^^^^^^^^^^^
+
+The mesh blueprint does yet not have a prescribed winding convention (a way to order the association of vertices to elements) or more generally to 
+outline a topology's `dimensional cascade`  (how elements are related to faces, faces are related to edges, and edges are related to vertices. )
+
+This is a gap we are working to solve in future versions of the mesh blueprint, with a goal of providing transforms to
+help converting between windows, or different cascade schemes. 
+
+That said VTK (and VTK-m) winding conventions are assumed by MFEM, VisIt, or ALPINE when using Blueprint data.
+
+
 .. * **stream** - (strem description)
 ..   (specifying stream ids and stream connectivity)
 ..
@@ -334,6 +347,15 @@ Thus, to conform to protocol, each entry under the ``fields`` section must be an
 
 
 
+
+Topology Association for Field Values
+======================================
+
+For implicit topologies, the field values are associated with the topology by fast varying logical dimensions starting with ``i``, then ``j``, then ``k``.
+
+For explicit topologies, the field values are associated with the topology by assuming the order of the field values matches the order the elements are defined in the topology. 
+
+
 Adjacency Sets
 ++++++++++++++++++++
 

src/docs/sphinx/building.rst

@@ -59,6 +59,17 @@ Clone the Conduit repo:
     
     git clone --recursive https://github.com/llnl/conduit.git
 
+
+``--recursive`` is necessary because we are using a git submodule to pull in BLT (https://github.com/llnl/blt). 
+If you cloned without ``--recursive``, you can checkout this submodule using:
+
+.. code:: bash
+    
+    cd conduit
+    git submodule init
+    git submodule update
+
+
 Configure a build:
 
 ``config-build.sh`` is a simple wrapper for the cmake call to configure conduit. 
@@ -148,7 +159,7 @@ The ``config-build.sh`` script uses your machine's hostname, the SYS_TYPE enviro
 
 You can find example files in the ``host-configs`` directory. 
 
-These files use standard CMake commands. CMake *set* commands need to specify the root cache path as follows:
+These files use standard CMake commands. To properly seed the cache, CMake *set* commands need to specify ``CACHE`` as follows:
 
 .. code:: cmake
 

src/docs/sphinx/developer.rst

@@ -99,6 +99,19 @@ Adding a Unit Test
 - Add the test to build system by editing ``src/tests/{lib_name}/CMakeLists.txt``
 
 
+Running Unit Tests via Valgrind
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We can use ctest's built-in  valgrind support to check for memory leaks in unit tests. Assuming valgrind is automatically detected when you run CMake to configure conduit, you can check for leaks by running:
+
+.. code:: bash
+    
+    ctest -D ExperimentalBuild
+    ctest -D ExperimentalMemCheck
+    
+The build system is setup to use **src/cmake/valgrind.supp** to filter memcheck results. We don't yet have all spurious issues suppressed, expect to see leaks reported for python and mpi tests. 
+
+
 BLT
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Conduit's CMake-based build system uses BLT (https://github.com/llnl/blt).

src/docs/sphinx/index.rst

@@ -107,8 +107,6 @@ Conduit Libraries
 
 The *conduit* library provides Conduit's core data API. The *relay* and *blueprint* libraries provide higher-level services built on top of the core API. 
 
-.. note::
-    **Caveat Emptor**: The APIs for *relay* and *blueprint* are still in flux.
 
 conduit
 ~~~~~~~~

src/docs/sphinx/licenses.rst

@@ -58,7 +58,7 @@ Here is a list of the software components used by conduit in source form and the
 
 C and C++ Libraries
 =====================
-- *gtest*: thirdparty_builtin/gtest-1.7.0/LICENSE (BSD Style License)
+- *gtest*: From BLT - (BSD Style License)
 - *libb64*: thirdparty_builtin/libb64/LICENSE (Public Domain)
 - *rapidjson*: thirdparty_builtin/rapidjson/license.txt (MIT License)
 - *civetweb*: thirdparty_builtin/civetweb-1.8/LICENSE.md (MIT License)
@@ -72,11 +72,12 @@ JavaScript Libraries
 
 Fortran Libraries
 =====================
-- *fruit*: thirdparty_builtin/fruit-3.3.9/LICENSE.txt (BSD Style License)
+- *fruit*: From BLT - (BSD Style License)
 
 Build System
 ~~~~~~~~~~~~~~~
 - *CMake*: http://www.cmake.org/licensing/ (BSD Style License)
+- *BLT*: https://github.com/llnl/blt (BSD Style License)
 - *Spack*: http://software.llnl.gov/spack (LGPL License)
 
 

src/docs/sphinx/relay_mpi.rst

@@ -63,8 +63,6 @@ Supported MPI Primitives:
  * reduce/all_reduce
  * broadcast
  * gather/all_gather
- * scatter
- * all_to_all (?)
 
 
 For both point to point and collectives, here is the basic logic for how input Nodes are treated by these methods:
@@ -92,9 +90,6 @@ Supported MPI Primitives:
   * send/recv
   * gather/all_gather
   * broadcast
-  * scatter (?)
-  * all_to_all
-
 
 
 Unsupported MPI Primitives:

src/docs/sphinx/releases.rst

@@ -50,6 +50,50 @@ Source distributions for Conduit releases are hosted on github:
 
 https://github.com/LLNL/conduit/releases
 
+.. note:: As of v0.3.0, Conduit uses `BLT <https://github.com/LLNL/blt>`__ as its core CMake build system. We leverage BLT as a git submodule, however github does not include submodule contents in its automatically created source tarballs. To avoid confusion, starting with v0.3.0 we will provide our own source tarballs that include BLT. 
+
+v0.3.0
+-----------------
+
+* `Source Tarball <https://github.com/LLNL/conduit/releases/download/v0.3.0/conduit-v0.3.0-src-with-blt.tar.gz>`__
+* `Docs <http://software.llnl.gov/conduit/v0.3.0>`__
+
+
+Highlights
++++++++++++++
+
+* **General**
+
+ * Moved to use BLT (https://github.com/llnl/blt) as our core CMake-based build system
+ * Bug fixes to support building on Visual Studio 2013
+ * Bug fixes for `conduit::Nodes` in the List Role
+ * Expose more of the Conduit API in Python
+ * Use ints instead of bools in the Conduit C-APIs for wider compiler compatibility   
+ * Fixed memory leaks in *conduit* and *conduit_relay*
+
+
+* **Blueprint**
+
+ * Mesh Protocol
+
+   * Added support for multi-material fields via *matsets* (volume fractions and per-material values)
+   * Added initial support for domain boundary info via *adjsets* for distributed-memory unstructured meshes  
+
+
+* **Relay**
+
+ * Major improvements *conduit_relay* I/O HDF5 support 
+
+   * Add heuristics with knobs for controlling use of HDF5 compact datasets and compression support
+   * Improved error checking and error messages 
+
+ * Major improvements to *conduit_relay_mpi* support 
+
+   * Add support for reductions and broadcast
+   * Add support zero-copy pass to MPI for a wide set of calls
+   * Harden notion of `known schema` vs `generic` MPI support
+
+
 v0.2.1
 -----------------