Skip to content

Latest commit

 

History

History
146 lines (124 loc) · 5.56 KB

README.md

File metadata and controls

146 lines (124 loc) · 5.56 KB
Raw
         .___              
       __| _/____     ____ 
      / __ |\__  \   / ___\
     / /_/ | / __ \_/ /_/  > 
     \____ |(____  /\___  /
          \/     \//_____/

Overview

DAG is a Fortran 2018 library for creating and manipulating directed acyclic graphs (DAGs).
DAG is based on a fork of daglib by Jacob Williams, refactored to

  • Adopt a functional programming pattern based on (mostly) pure functions.
  • Add build system and test harness automated by fpm,
  • Add unit testing written with veggies,
  • Add continuous-integration testing and documentation deployment via GitHub Actions,
  • Add documentation generated by FORD,
  • Add runtime assertion-checking using Assert, and
  • Add JSON file input/output using rojff.
  • Ensure that dag objects always have a valid state that includes a topological ordering stored without mutating vertices or vertex arrays.

Usage

When compilers cooperate, we recommend using associate to assign names to dag's user-defined structure constructor results. See the example subdirectory for demonstrations of how we use associate instead of the declare-and-define style that is much more common in Fortran and other imperative programming languages. Associating a name instead of declaring an object and then later defining it offers several potential advantages:

  • It prevents the accidental use of declared-but-undefined data.
  • It provides immutable state, which in turn
    • prevents the mistaken overwriting of data and
    • enables some possible compiler optimizations.

Caveat emptor: your mileage may vary. Compiler support for associate is evolving and compiler might or might not exploit optimizatio opportunities. When weird things happen, resort to declaring and subsequently defining objects by assigning a constructor function result to the declared object.

Prerequisites

The fpm package manager automatically downloads and builds all dependencies. See [fpm.toml] for a complete list, including version numbers.

Downloading

Obtain dag by downloading the latest release or cloning the repository as follows:

git clone git@github.com:sourceryinstitute/dag

Building and testing

Building and testing for serial execution

Build and test dag in a bash-like shell as follows:

fpm test

Building and testing for parallel execution

With gfortran and OpenCoarrays installed, build and test dag in a bash-like shell as follows:

fpm test --compiler caf --runner "cafrun -n 2"

replacing 2 in the last line with the desired number of images to execute in parallel for each test.

Please report any test failures by submitting an issue on the DAG repository.

Examples

The example subdirectory provides the following examples:

  • print-to-json.f90 - constructs and prints it a JSON representation the DAG. Run this example and redirect the output to a file as follows:
fpm run --example print-to-json > dag.json
  • read-from-json.f90 - constructs a DAG by reading from a JSON file. Run this example as follows:
fpm run --example read-from-json

which will read the file ./example/dag-dependencies.json

  • dag-to-dot.f90 - constructs a DAG describing the module dependencies in
    an early version of the Framework for Extensible Asynchronous Task Scheduling (FEATS) and prints the DAG to a .dot file suitable for conversion to a .pdf as follows:
fpm run --example dag-to-dot > feats-dag.dot
dot -Tpdf -o feats.pdf feats.dot

which should produce the following graph below:

feats-dependencies

License

This library is released under a BSD-3 license.

Acknowledgments
We gratefully acknowledge support from NASA Langley Research Center under contract number 80NSSC20P2246. NASA logo

Donate

If you find this software useful, please consider donating code or currency to aid in development efforts.