Merge pull request #81 from sourceryinstitute/develop

Merge Develop into master ahead of release

Author: zbeekman

.github/workflows/FORD.yml

@@ -52,11 +52,12 @@ jobs:
           mkdir -p $(brew --cache) || true
           ford -r $(git describe --always) --debug API-doc-FORD-file.md
           touch API-doc/.nojekyll
+          zip -vr API-docs.zip API-doc/ -x "*.DS_Store"
       - name: Upload Documentation
         uses: actions/upload-artifact@v1
         with:
           name: FORD-API-docs
-          path: ./API-doc
+          path: ./API-docs.zip
 
   Check-Links:
     runs-on: ubuntu-latest
@@ -69,7 +70,11 @@ jobs:
         uses: actions/download-artifact@v1
         with:
           name: FORD-API-docs
-          path: ./API-doc
+          path: ./
+      - name: Extract source zip
+        run: |
+          unzip API-docs.zip
+          ls -la
       - name: set git vars
         id: sgv
         run: |
@@ -79,7 +84,7 @@ jobs:
         uses: peter-evans/link-checker@v1
         id: lc
         with:
-          args: -c 5 -v -r -x (gsellc\.com$)|(github\.com\/cmacmackin\/ford$)|(gcc\.gnu\.org\/onlinedocs\/gfortran)|(\/interface\/operator) API-doc
+          args: -c 5 -v -r -x (gsellc\.com$)|(github\.com\/cmacmackin\/ford$)|(gcc\.gnu\.org\/onlinedocs\/gfortran)|(\/interface\/operator)|(gcc.gnu.org/bugzilla) API-doc
       - name: Prune OK links
         id: pol
         if: steps.lc.outputs.exit_code != 0
@@ -94,6 +99,7 @@ jobs:
           pr_msg="${pr_msg//$'\n'/'%0A'}"
           pr_msg="${pr_msg//$'\r'/'%0D'}"
           echo "::set-output name=pr_msg::$pr_msg"
+          sed '/^[[:space:]]*OK[[:space:]]/d' < issue.md
       - name: Create Issue From File
         uses: peter-evans/create-issue-from-file@v2
         if: github.event_name == 'push' && ( github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop' || endsWith( github.ref , '-dev' ) )

API-doc-FORD-file.md

@@ -83,7 +83,7 @@ In addition to the search box on the right side of the top navbar, the following
 * [Developer Documentation]:  
   Visit the high-level developer documentation which outlines
     - How to get started,
-    - Procedures and classes most relavent to creating or modifying a PDE solver, and
+    - Procedures and classes most relevant to creating or modifying a PDE solver, and
     - Instructions for building the Morfeus Framework library
     - A high-level overview of the CMake based build system
 * [Source Files]:  
@@ -93,7 +93,7 @@ In addition to the search box on the right side of the top navbar, the following
   the [Modules] landing page.
 * [Modules]:  
   The landing page enumerating and describing all the modules and submodules in the project.
-  More usefull than the Source Files page, as it groups submodules with their parent modules and
+  More useful than the Source Files page, as it groups submodules with their parent modules and
   provides some description for what each one does.
 * [Procedures]:  
   Enumerates all procedures including generic overloaded interfaces, operators, module procedures, functions and subroutines.

API-doc-style.css

@@ -7,3 +7,5 @@ th, td {
 }
 
 tr:nth-child(even) {background-color: #f2f2f2;}
+
+#responsive-image {  width: 100%;  height: auto; }

README.md

@@ -31,7 +31,7 @@
 ### Capabilities
 
 MORFEUS is an open source framework for the solution of partial differential equations
-(PDEs) written in modern Fortran. It is object oriented, and attempts to provide usefull
+(PDEs) written in modern Fortran. It is object oriented, and attempts to provide useful
 abstractions for the solution of PDEs that are easy to use and performant.
 
 MORFEUS consists of two main solution approaches:

developer-doc/FD-API.md

@@ -27,12 +27,12 @@ Solver and Problem Setup
 @todo
 This needs more text added here.
 
-Timestepping and Integration
+Time-stepping and Integration
 ----------------------------
 
 @todo
 This needs more text added here.
-Pressumably something better than forward Euler is being used...
+Presumably something better than forward Euler is being used...
 
 \begin{equation}
 u_i^{n+1} = u_i^n + \Delta_t f(t,u_i^n)

developer-doc/FD-API.md.bak

@@ -0,0 +1,156 @@
+---
+title: High-level FD API documentation
+---
+
+
+<details><summary><b>Table of Contents</b></summary>
+
+[TOC]
+
+</details>
+
+@warning The block-structure parallel FD solver is still a work in progress
+
+Overview
+--------
+
+Here an overview of the Morfeus finite difference (FD) framework is given.
+Included is a brief description of how to setup a new solver using the framework.
+Key objects/classes, and procedures are outlined.
+An overview of reading input files, reading grid files,
+initializing the library and data structures and, setting up PDEs, integrating the solution forward in time
+and writing outputs is given.
+
+Solver and Problem Setup
+------------------------
+
+@todo
+This needs more text added here.
+
+Timestepping and Integration
+----------------------------
+
+@todo
+This needs more text added here.
+Pressumably something better than forward Euler is being used...
+
+\begin{equation}
+u_i^{n+1} = u_i^n + \Delta_t f(t,u_i^n)
+\end{equation}
+
+High Level Classes and Objects
+------------------------------
+
+Below is a list of the important high-level objects and classes, with a brief discussion and
+links to detailed API documentation and their implementations.
+A complete list of all FD and FV classes and types can be found on the [types list page].
+
+[types list page]: ../lists/types.html
+
+@todo
+This needs updating/finishing
+
+
+### [[object(type)]]
+
+`[[object(type)]]` is an abstract type to ensure descendents declare the required deferred bindings to
+
+#### Methods
+
+* `[[object(type):mark_as_defined]]` : Set the object as defined
+* `[[object(type):user_defined]]` : Query whether the object is defined
+
+### [[grid(type)]]
+
+`[[grid(type)]]` Is the Morfeus universal base type for all grids, even for FV grids. It extends `[[object(type)]]`.
+
+#### Methods
+
+* `[[grid(type):set_units]]` : Set the physical units used by the grid
+* `[[grid(type):get_units]]` : Get the physical units used by the grid
+
+### [[structured_grid(type)]]
+
+This is the main structured grid class used by Morfeus FD. It extends the `[[grid(type)]]` class.
+Methods defined for this class can get information about the global grid as well as this images particular block.
+
+#### Methods
+
+@todo
+This section needs to be filled in/expanded!
+
+* `[[structured_grid(type):clone]]` :
+* `[[structured_grid(type):space_dimension]]` :
+* `[[structured_grid(type):set_metadata]]` :
+
+### [[cartesian_grid(type)]]
+
+@todo
+add description and how to use, etc.
+
+#### Methods
+
+@todo
+discussion of important methods provided and how to use them, etc.
+
+### [[curvilinear_grid(type)]]
+
+@todo
+add description and how to use, etc.
+
+#### Methods
+
+@todo
+discussion of important methods provided and how to use them, etc.
+
+### [[co_object(type)]]
+
+
+### [[surfaces(type)]]
+
+
+### [[material_t(type)]]
+
+
+### [[thickness_t(type)]]
+
+
+### [[problem_discretization(type)]]
+
+
+### [[package(type)]]
+
+
+### [[material_t(type)]]
+
+
+### [[flux_planes(type)]]
+
+
+### [[plate_3D(type)]]
+
+
+### [[geometry(type)]]
+
+
+### [[subdomain_t(type)]]
+
+
+### etc., etc.
+
+
+High Level Procedures and Methods
+---------------------------------
+
+All Morfeus FV and FD procedures are listed on the [procedures list page], but below is a curated list of those that correspond to high-level
+operations in FD. These should help you write your own programs and kernels using Morfeus FD.
+
+[procedures list page]: ../lists/procedures.html
+
+### [[assert(proc)]]
+
+`[[assert(proc)]]` Is an assertion utility used in design by contract (DBC) for enforcing pre-conditions, post-conditions and invariants, as well in testing.
+
+
+@todo
+Add other stand-alone procedures used to instantiate objects of for other purposes where a TBP method is not used.

developer-doc/FV-API.md

@@ -23,7 +23,7 @@ is provided and its components described along with instructions for
   - Setting up PDEs and integrating the solution forward in time, and
   - Writing outputs.
 
-![Sphere geometry and mesh for finite volume solver](https://user-images.githubusercontent.com/13108868/74580343-f5095500-4f57-11ea-9c18-5c5aec301642.png)
+![Sphere geometry and mesh for finite volume solver](../media/sphere.png)
 
 
 Solver Description
@@ -41,7 +41,7 @@ The morfeus solver consists of two parts:
 Numerical Algorithms
 --------------------
 
-Morfeus-FV solves transport equations using explicit finite-difference time advancement and cell-based finite-volume scheme spatial discretizations.  For a complete description of the alogorithms employed
+Morfeus-FV solves transport equations using explicit finite-difference time advancement and cell-based finite-volume scheme spatial discretizations.  For a complete description of the algorithms employed
 in Morfeus-FV, refer to the dissertation by S. [Toninel (2006)].  More recent work has involved modernization of the code using the modular and object-oriented programming (OOP) features of Fortran 2008,
 including
 
@@ -50,14 +50,29 @@ including
   - User-defined, type-bound operators, and
   - Submodules.
 
-[Toninel (2006)]: http://people.uniroma2.it/salvatore.filippone/nemo/toninel_phd.pdf
+[Toninel (2006)]: ../media/toninel_phd.pdf
 
 Input Files
 ------------
 
 Morfeus requires two input files. The first is a geometry file in GAMBIT neutral file format or in EXODUS II format; the second is a file called fast.json that contains the problem description, i.e. the description of materials, boundary conditions, solver parameters such as convergence criteria, and output parameters. The `fast.json` file should be present in the same folder as the mesh-file and the solver.   The next several sections describe different sections of a [sample json input file].
 
-[sample json input file]: https://github.com/sourceryinstitute/OpenCoarrays/files/4207672/fast.json.zip
+[sample json input file]: ../media/fast.json
+
+Example Program Flow
+--------------------
+
+A typical multi-physics application for dealing with heat transfer, solid mechanics, and various other physics would look something like the figure below:
+
+<img src="../media/Morfeus-FV-program-flow.png" id="responsive-image">
+
+It might not be immediately obvious how to connect these high-level concepts to the particular objects, classes and their methods listed below.
+The following figure provides a mapping to connect these abstract concepts to their more concrete realization.
+
+<img src="../media/Flowchart.png" id="responsive-image">
+
+Additional information about the objects, classes and their mothods (type bound procedures) shown on the right hand side of the preceding figure can be found below.
+This information includes direct links to the more detailed API documentation.
 
 High-Level Object Descriptions
 ------------------------------