diff --git a/README.md b/README.md
index 0d0646fa3589ae0432e0237fcd6affc20293c80f..20bd9094042419a7b6eb1e2f96f1f30d3a304d7d 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,107 @@
-## What
+## General Description
+
+Library for [OpenFOAM] that provides a runtime-selectable
+function object for embedding [ParaView Catalyst][Catalyst]
+in-situ visualization into arbitrary OpenFOAM simulations.
+
+Supports in-situ conversion of the following types:
+- finite volume meshes and fields. Single or multi-region.
+- finite area meshes and fields. Single region.
+- lagrangian (clouds). Single or multiple clouds.
+
+### Overset
+
+For simulations with overset meshes, internal blanking is used to hide
+the *holes* so that user visualization pipelines do not require any
+thresholding workarounds. Note, however, that visualization artifices
+may be present in multi-overlapping regions.
-Library and function object for embedding ParaView Catalyst into OpenFOAM.
## Requirements
-1. OpenFOAM.com development version (11-May-2018 or newer) or OpenFOAM-v1806.
-2. ParaView or ParaView Catalyst 5.5 or newer, compiled with python support
- (optionally with MPI support).
+1. [OpenFOAM-v1806] or a recent [development version][OpenFOAM-git]
+ from [OpenFOAM.com][OpenFOAM].
+2. [ParaView] or ParaView [Catalyst] 5.5 or newer,
+ compiled with python support (optionally with MPI support).
+
+
+### Patching
+
+It is **highly recommended** to patch the ParaView 5.5 sources to
+include changes ([MR2433], [MR2436]) that will be part of the
+ParaView 5.6 release.
+
+These patches are necessary to ensure that the in-situ results are
+placed in the correct output directory.
+Without these patches, the results will always land in the current
+working directory: not in the case-local `insitu` subdirectory
+and ignoring the OpenFOAM `-case` parameter.
+
+These [patches] will be automatically applied when the `makeParaView`
+script from OpenFOAM ThirdParty is used.
+
+
+## Building
-It is highly recommended to patch the ParaView 5.5 sources (eg, using the
-OpenFOAM ThirdParty makeParaView script) to ensure that they properly handle
-outputting results in directories other than the main simulation directory:
+Ensure that the OpenFOAM environment is active and that ParaView or Catalyst
+can be found (Eg, the `ParaView_DIR` environment is properly set).
-* [MR2433]
-* [MR2436]
+
+### With the OpenFOAM `wmake`
+
+Simply use the supplied `Allwmake` script:
+````
+./Allwmake
+````
+This will install into `$FOAM_LIBBIN`
+
+
+### With `cmake` directly
+
+Without parameters, it installs to `$FOAM_LIBBIN` as the default output
+location for the library.
+
+````
+mkdir build; cd build
+cmake ../src/catalyst
+````
+which is identical to
+````
+mkdir build; cd build
+cmake -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=default ../src/catalyst
+````
+
+To specifying an alternative library location, change the cmake parameter:
+
+````
+mkdir build; cd build
+cmake -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=/output/path/lib ../src/catalyst
+````
+
+The cmake configuration possibilities are functional, but still very
+**rudimentary** at the moment.
## Authors
-* Mark Olesen <Mark.Olesen@esi-group.com>
-* Simone Bna <Simone.Bna@cineca.it>
+- Mark Olesen | <Mark.Olesen@esi-group.com> | (ESI-OpenCFD)
+- Simone Bna | <Simone.Bna@cineca.it> | (CINECA)
## License
-Same terms as OpenFOAM.
-Licensed under GNU General Public License <http://www.gnu.org/licenses/>.
+Licensed under GNU General Public License <http://www.gnu.org/licenses/>
+with the same terms as OpenFOAM itself.
+
+----
+
+[OpenFOAM]: https://www.openfoam.com
+[OpenFOAM-v1806]: https://www.openfoam.com/releases/openfoam-v1806/
+[OpenFOAM-git]: https://develop.openfoam.com/Development/OpenFOAM-plus
+[patches]: https://develop.openfoam.com/Development/ThirdParty-plus/raw/develop/etc/patches/paraview-5.5.2
+[ParaView]: https://www.paraview.org/
+[Catalyst]: https://www.paraview.org/in-situ/
[MR2433]: https://gitlab.kitware.com/paraview/paraview/merge_requests/2433
[MR2436]: https://gitlab.kitware.com/paraview/paraview/merge_requests/2436
diff --git a/src/catalyst/CMakeLists-Common.txt b/src/catalyst/CMakeLists-Common.txt
index 8f46668d28d938d426e59ba1c84361412ce0e585..a484dbebf8b04f492f1a0a92bc293e614dbfbc4d 100644
--- a/src/catalyst/CMakeLists-Common.txt
+++ b/src/catalyst/CMakeLists-Common.txt
@@ -56,12 +56,12 @@ else()
endif()
-# Set output library destination to OpenFOAM library directory
-set(LIBRARY_OUTPUT_PATH $ENV{FOAM_LIBBIN}
+set(LIBRARY_OUTPUT_PATH ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}
CACHE INTERNAL
""
)
+
file(GLOB SOURCE_FILES
catalystCoprocess.C
catalystTools.C
@@ -85,12 +85,12 @@ file(GLOB SOURCE_FILES
set(OPENFOAM_LIBRARIES
OpenFOAM
+ Pstream
finiteArea
finiteVolume
fileFormats
- conversion
- Pstream
meshTools
+ conversion
lagrangian
overset
)
diff --git a/src/catalyst/CMakeLists.txt b/src/catalyst/CMakeLists.txt
index b84df5b0774884b4a95d87cfd87de7da60927619..9e210ab65257f9a91eeb04217a7145d606a3e0b5 100644
--- a/src/catalyst/CMakeLists.txt
+++ b/src/catalyst/CMakeLists.txt
@@ -1,21 +1,58 @@
+#------------------------------------------------------------------------------
cmake_minimum_required(VERSION 2.8)
+# Fail immediately if not using an out-of-source build
+if (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR)
+ message(FATAL_ERROR
+ "In-source builds are not supported. Please create a build directory "
+ "separate from the source directory")
+endif()
+
project(catalyst)
# Set policy for CMP0002 needed for cmake > 3
cmake_policy(SET CMP0002 OLD)
+
+#------------------------------------------------------------------------------
+# Simple sanity checks
+
+if (NOT EXISTS "$ENV{WM_PROJECT_DIR}")
+ message(FATAL_ERROR "WM_PROJECT_DIR not set")
+endif()
+
if (EXISTS "$ENV{ParaView_DIR}")
- message("Building with Paraview from $ENV{ParaView_DIR}")
find_package(ParaView REQUIRED COMPONENTS vtkPVPythonCatalyst)
- if (NOT PARAVIEW_USE_MPI)
- message(WARNING "==== Recommended to build using ParaView Catalyst with MPI ====")
- endif()
else()
- message (FATAL_ERROR "ParaView_DIR not set")
+ message(FATAL_ERROR "ParaView_DIR not set")
endif()
-include(CMakeLists-Common.txt)
+#------------------------------------------------------------------------------
+# Installation locations (not much)
+# - default install into FOAM_LIBBIN
+
+if ((NOT CMAKE_LIBRARY_OUTPUT_DIRECTORY) OR
+ ("${CMAKE_LIBRARY_OUTPUT_DIRECTORY}" STREQUAL "default"))
+ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY $ENV{FOAM_LIBBIN})
+endif()
+
+
+#-----------------------------------------------------------------------------
+# All messages
+
+message("================")
+message("Using OpenFOAM = $ENV{WM_PROJECT_DIR}")
+message("Using ParaView = $ENV{ParaView_DIR}")
+if (NOT PARAVIEW_USE_MPI)
+ message(WARNING "==== Recommended to build using ParaView Catalyst with MPI ====")
+endif()
+message("install libdir = ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}")
+message("================")
+
+
+#-----------------------------------------------------------------------------
+
+include(CMakeLists-Common.txt)
#-----------------------------------------------------------------------------
diff --git a/src/catalyst/catalystFunctionObject.C b/src/catalyst/catalystFunctionObject.C
index 0472baebed83cbb9e7da98ecf571512d02cc0b7b..cf8fedae3f70892c6a1d7f88efdb1ac51e2dceb5 100644
--- a/src/catalyst/catalystFunctionObject.C
+++ b/src/catalyst/catalystFunctionObject.C
@@ -292,12 +292,24 @@ bool Foam::functionObjects::catalystFunctionObject::execute()
if (nChannels)
{
+ if (catalyst::coprocess::debug > 1)
+ {
+ Pout<< type() << ": query catalyst for " << nChannels
+ << " channels" << nl;
+ }
+
nChannels = adaptor_().query(dataq);
}
- if (catalyst::coprocess::debug)
+ if (catalyst::coprocess::debug > 1)
+ {
+ Pout<< type() << ": query catalyst for " << nChannels
+ << " channels" << nl;
+ }
+ else if (catalyst::coprocess::debug)
{
- Info<< type() << ": expecting data for " << nChannels << nl;
+ Info<< type() << ": expecting data for " << nChannels
+ << " channels" << nl;
}
if (!nChannels)
@@ -307,11 +319,22 @@ bool Foam::functionObjects::catalystFunctionObject::execute()
catalyst::outputChannels outputs;
+ if (catalyst::coprocess::debug > 1)
+ {
+ Pout<< type() << ": converting input" << nl;
+ }
+
for (auto& inp : inputs_)
{
inp.convert(dataq, outputs);
}
+ if (catalyst::coprocess::debug > 1)
+ {
+ Pout<< type() << ": sending data for" << outputs.size()
+ << " outputs" << nl;
+ }
+
if (outputs.size())
{
Log << type() << ": send data" << nl;
@@ -320,6 +343,12 @@ bool Foam::functionObjects::catalystFunctionObject::execute()
}
+ if (catalyst::coprocess::debug > 1)
+ {
+ Pout<< type() << ": done step" << nl;
+ }
+
+
// Avoid compiler complaint about unused variable.
// - manually restore old SIGFPE state
sigFpeHandling.restore();