/literate-hdf5

“Tell me the facts and I’ll learn. Tell me the truth and I’ll believe. But tell me an HDF5 story and it will live in my heart forever.” (Native American proverb)

Primary LanguageC

Table of Contents

Caveat Emptor

Each example in this collection tells a story and, to a degree, is fiction. The reality and demands of professional software development are much harsher, and are not met by the code examples provided. For example, no error detection or handling was attempted, and attentive readers will easily identify several corner cases that were not considered. The code examples in this collection are for illustration only.

Cohortatio ad Gentiles

Enjoy perusing the Org (text!) files rendered reasonably well courtesy of GitHub. Believe it or not, all artifacts (code examples, images, etc.) are generated from the Org files, but they are repeated for your convenience in the appropriate sub-directories.

If you develop a sense that you are missing a lot, consider learning Emacs and becoming an Emacs master.

To Emacs Users

Derek Feichtinger’s repo of Org Babel examples is a constant source of inspiration. Check it out!

For your own sanity and that of those around you, I recommend you first run through the checklist.

There are several ways to run the C examples contained in these documents. You can execute the code blocks containing main functions directly via C-c C-c , provided the HDF5 library is in your LD_LIBRARY_PATH and GCC knows where to find the HDF5 header files and library. If the h5cc compiler wrapper is in your PATH, execute the following block:

(setq org-babel-C-compiler "h5cc --std=gnu99 ")

For parallel HDF5 examples use:

(setq org-babel-C-compiler "HDF5_CC=mpicc h5cc --std=gnu99 ")

and don’t forget to link against the MPI library!

(Caveat: I have not yet figured out a way to invoke the executable with mpirun/mpiexec/srun.)

Otherwise, you have to be more specfic. For example:

(setq org-babel-C-compiler
      (concat "gcc --std=gnu99 "
              "-I/home/gerdheber/.local/include "
              "-L/home/gerdheber/.local/lib "))

You will also need to specify the libraries against which to link with a :libs source code block header. (See C, C++, D Source Code Blocks in Org Mode.)

Create the examples’ source code by “tangling” via C-c C-v t from Emacs or from the command line by running

emacs --batch --eval "(require 'org)" \
      --eval '(org-babel-tangle-file "<filename>.org")'

Or run make tangle for wholesale “entanglement.”

The code can then be compiled with gcc --std=gnu99 ... and the appropriate include and library paths for HDF5, MPI, etc.

Finally, you can create a static HTML dump of this project by configuring the org-publish-project-alist variable. For example:

(setq org-publish-project-alist
 '(("literate-hdf5"
    :base-directory "~/GitHub/literate-hdf5"
    :base-extension "org"
    :publishing-function org-html-publish-to-html
    :publishing-directory "~/public_html"
    :section-numbers nil
    :table-of-contents nil
    :auto-preamble t)
   ("literate-hdf5-supplement"
    :base-directory "~/GitHub/literate-hdf5"
    :base-extension "css\\|png\\|jpg\\|gif"
    :publishing-directory "~/public_html/"
    :recursive t
    :publishing-function org-publish-attachment)))

Run C-c C-e P x and select the respective component. The literate-hdf5 component generates the HTML, while literate-hdf5-supplement copies the images, etc.

See Publishing Org-mode files to HTML for details.