.. _dataprovider-openfoam-page:

#############################
OpenFOAM Plugin 
#############################

********
Overview
********

The OpenFOAM Data Provider Plugin has been developed using :ref:`data-provider-framework-page`.

The provider can be plugged into applications based on *HOOPS Envision for Desktop*. This includes 
HOOPS Envision Demo Analyzer and the RemoteModel server (UgServer) in |WebProductName|. 
The same plugin can be used both on web and desktop.

The cdp_OpenFoam plugin provides the following data based on a given ModelKey:

-   Meta data about the given model: Number of states (OpenFoam increments), geometries (OpenFoam parts + boundaries), results
-   CAE model with elements and nodes
-   Results: Scalar, Vector, Displacements (mesh changes according to the time-step for OpenFOAM AMI results) and Tensor
-   Rigid body transformations
-   Element sets

The cdp_OpenFoam plugin also supports communicating updated data to the host application. This is done via the 
:func:`pollForChanges() <cee::imp::cae::DataSourceCae::pollForChanges()>` 
This methods allows for notifying the host application that data has changed and the host will then ask for the updated 
data whenever needed.

The following modifications are supported in the cdp_OpenFoam plugin:

-   Results: Modified, added and deleted -> supported if all results are added/removed together with the state folder
-   States: Modified meta data (name and reference value), added and deleted -> recognizes single or multiple states and 
    their results (added/delete), then sorted according the reference value 
-   Geometry: Modified -> NOT YET SUPPORTED : However, Geometry changes such as AMI points update are handle 

The OpenFoam data provider plugin will then be used as first priority to open all your .foam files.
If the built-in openFoam reader should be used, just delete the cdp_OpenFoamPlugin plugin from this path.


*****************
Available Options
*****************

The following options are supported by the OpenFOAM Data Provider:

==========================  ======= =========  ==================================================================================
Name                        Type    Default    Description
==========================  ======= =========  ==================================================================================
LOAD_BC_PARTS               boolean true       Load Boundary Parts
LOAD_CELL_ZONES             boolean true       Load Cell Zones
LOAD_FACE_ZONES             boolean false      Load Face Zones
NODE_AVG_RES                boolean true       Provide node average results
HIDE_PARALLEL_INTERFACES    boolean false      Hide Parallel Interfaces Between Processors
OF_SMART_MESH_LOAD          boolean true       Request to load local mesh first, if not found then use global mesh + cellzones
LOAD_GLOBAL_MESH            boolean true       Load Global Mesh i.e from constant/polyMesh + cell zones
LOAD_LOCAL_MESHES           boolean true       Load Local Meshes i.e from constant/region*/polyMesh
RESULTS_NAMES_MAPPING       string             U=Velocity;p=Pressure;rho=Density;T=Temperature;g=Gravity
IGNORE_PROCESSORS_FOLDERS   boolean false      Ignores the processor folder to use the reconstructed mesh in folder constant
==========================  ======= =========  ==================================================================================

For EnvisionWeb, use the :js:meth:`RemoteModel.setReaderOptions()` to specify these options before opening a file. 
For EnvisionDesktop, use the 
:func:`ReaderSettings::addDataProviderSettings() <cee::imp::cae::ReaderSettings::addDataProviderSettings()>` to specify 
these options before opening a file. 


********************************************************
Use in |ProductName|
********************************************************

Load the OpenFOAM data provider plugin using 
:func:`loadDataProviderPlugin() <cee::imp::cae::DataSourceCae::loadDataProviderPlugin()>` or load 
multiple plugins at once using 
:func:`loadDataProviderPluginsFromWildcard() <cee::imp::cae::DataSourceCae::loadDataProviderPluginsFromWildcard()>`.

Use the :func:`ReaderSettings::addDataProviderSettings() <cee::imp::cae::ReaderSettings::addDataProviderSettings()>` 
to specify these options before opening a file. 
See the list of available options for the OpenFOAM data provider in the list above.

Example:

.. code-block:: cpp

    for (size_t i = 0; i < cee::imp::cae::DataSourceCae::readerSettings().dataProviderSettingsCount(); ++i)
    {
        cee::imp::cae::ReaderSettingsDataProvider& settings = cee::imp::cae::DataSourceCae::readerSettings().dataProviderSettings(i);

        if (settings.providerIdString() == "OpenFoamProvider")
        {
            settings.setBoolValue("LOAD_BC_PARTS", true);
            settings.setBoolValue("NODE_AVG_RES", true);
        }
    }

*****************************************************************
Use in Envision Demo Analyzer Desktop
*****************************************************************

To use your data provider with Envision Demo Analyzer Desktop. When installed, the data provider plugins are in the 
**DataProviders** folder below the Analyzer executable. You can change this location by defining the environment 
variable **CEE_DATA_PROVIDERS_FOLDER** to point to the folder where your cdp_OpenFoamPlugin is located.
Envision Demo Analyzer will load the data providers from the specified folder.  

Polling of the data provider can be controlled by two settings in the **Advanced** panel of the **Settings** dialog:

-   Enable Data Provider polling
-   Show last state when a state is added

In the **Settings** dialog under the **Data Provider** panel there are specific settings for this plugin such as:

-   Load boundary parts: boundaries are read as parts and their name are followed by the suffix [BC]
-   Provide node average results: compute point data from cell data 
-   Hide parallel interfaces between processors: filter the BC parts whose names start with keyword 'procBoundary'
-   Result names mapping : possibility to express in the results list custom name for instance 
    U [Velocity OpenFOAM keyword] = Velocity [custom name]

once any of this settings edited, please reopen your case to account for this modification.



******************************************************
Use in |WebProductName|
******************************************************

Data providers can be used with the RemoteModel server (UgServer). To load your data provider, set the 
**CEW_UG_DATA_PROVIDER_FOLDER** environment variable to point to the folder with your data provider. The UgServer will 
load all data providers in the specified folder. The data provider needs to comply to the following naming scheme:

    cdp_OpenFoamPlugin.[dll|so|dylib]

Example:

    cdp_OpenFoamPlugin.dll (Windows), cdp_OpenFoamPlugin.so (Linux)

The server will list the registered OpenFOAM data provider plugin when a file is opened.

A data provider plugin can have a set of reader settings. For EnvisionWeb, use the 
:js:meth:`RemoteModel.setReaderOptions()` to specify these options before opening a file.
See the list of available options for the OpenFOAM data provider in the list above.

Example:

.. code-block:: ts

    this.m_model.setReaderOptions("OpenFoamProvider", { 
        "LOAD_BC_PARTS": true, 
        "NODE_AVG_RES": true
    });


*********
Changelog
*********

OpenFOAM
========

**Version 1.17.0 [March 5, 2025]**

- CAE-1486 : Fixed an issue where data results read incorrectly. Ensure that the reader continues to the next data 
  result buffer.

**Version 1.16.0 [November 6, 2024]**

- CAE-1432/SDC-684 : Fixed issue with crashing on some rare instances due to non-threadsafe code parallel parts of the 
  code. Changed Linux build to Rocky 8 (same as the Envision Web native addon)

**Version 1.15.0 [May 29, 2024]**

-   CAE-1362 : Add support for multi-dimensional (vector, tensor) node-averaged results for sampled surfaces

**Version 1.14.0 [March 1, 2023]**

-   CAE-901 : Modify triSurface parts support using triSurface patches for large number of sampled surface

**Version 1.13.0 [November 11, 2022]**

-   CAE-899 : Add flag (IGNORE_PROCESSORS_FOLDERS) to ignore processor folders in decomposed meshes. The mesh will be 
    load from folder /constant/polyMesh

**Version 1.12.0 [June 23, 2022]**

-   CAE-768 : Support for node average in triSurface parts

**Version 1.11.0 [May 24, 2022]**

-   CAE-719 : Add logic to load local mesh as priority first, if not found load global mesh + cell zones
-   CAE-526 : Add support for loading cell results in triSurface parts

**Version 1.10.0 [April 13, 2022]**

-   Built with CDP 7.0 (used by C3 4.5, CDC 3.10)

**Version 1.9.0 [March, 2022]**

-   Adding the possibility for loading local or global polymeshes [SDC-190]

**Version 1.8.0 [December 17, 2021]**

-   Upgraded to Ceetron Data Provider Framework 6.0

**Version 1.7.0 [November 5, 2021]**

-   Adding support for point result data such as "pointScalarField"

**Version 1.6.1 [October 25, 2021]**

-   Fixed reading of empty cell zones in multiple output formats.

**Version 1.6.0 [September 17, 2021]**

-   Adding support for results in single-line format.
-   Applying cell values in faces for the following boundary condition types: uniformFixedValue, slip and symmetry.

**Version 1.5.1 [February 5, 2021]**

-   Bug Fix : Handling cellZone reading when labelList is in the same line

**Version 1.5.0 [October 19, 2020]**

-   Speed improvements when getting geometry for larger cases.

**Version 1.4.3 [October 06, 2020]**

-   Ignoring Cells Zones for multi-region meshes.

**Version 1.4.2 [September 29, 2020]**

-   Fix: No suffix CZ for part names created from cell zones

**Version 1.4.1 [September 29, 2020]**

-   Fix: Reading when empty cellzones found.
-   Adding Part from elements not belonging to any cellZone.

**Version 1.4.0 [September 24, 2020]**

-   Added reading of Cell Zones as parts
-   Added reading of Face Zones as parts

**Version 1.3.3 [July 29, 2020]**

-   Fixed issue with FaceList reading of polymesh 

**Version 1.3.2 [July 17, 2020]**

-   Fixed an issue with OpenFOAM folders with symbolic links not working
-   Linux version is now built with Ubuntu 16.04 to fix intermittent crashes on some specific OpenFOAM files.

**Version 1.3.1 [July 17, 2020]**

-   Fixed an issue with OpenFOAM folders with symbolic links not working

**Version 1.3.0 [July 11, 2020]**

-   Creation of makeCustomName and makeIdString methods from openFoam resultNativeNames
-   Using idstring to be compatible with previous reader : vdm idstrings

**Version 1.2.0 [May 27, 2020]**

-   Added nodeAverageAwareBoundaryConditions to reproduce previous reader implementation
-   Defining method close() for provider
-   Added custom results namings, idString.
-   Added units in provider
-   Matching result_names_mapping (default values) with vdm reader.
-   Forcing states id to start by 1000 and be of type : 1001,1002,1003,.....
-   Fix field reading when finding the data in the same line of the keyword uniform or non-uniform.

**Version 1.1.0 [April 21, 2020]**

-   Added SimulationInfo for openFoam DP cases
-   Fix orientation of facenodes to point outwards the face of each cell.
-   Fixed metadata of boundary ids, when filtering some BCs. Now the Ids are consecutive (Part1, all_BCs_part1, Part2, 
    all_bcs_part2, etc ...).
-   Memory footprint test by changing cdp_int_t to cdp_ubyte_t for arrays containing element faceCount, element 
    nodeCount and element face nodeCount if element is polyhedron type
-   Parallel strategy to get geometry deploying threads for each part.
-   Parallel strategy to get results by part deploying threads for each part.
-   Extended partInfo to include parentId and also added attributes.
-   Defined DisplacementResult from state folder points
-   Poll for changes taking into account added/edited/removed single or multiple states. Regardless of the manipulation 
    to the state folder's, it is more stable now.
-   Compute average node result from volume data
-   Reading boundaries values from file.
-   Added method filterBoundaryByName(..) in order to filter the boundaries pathName starting with the keyword 
    'boundaryProc'. Added as readerSetting.
-   Added option to create nodal results from cell data. Added as ReaderStetting
-   Added link between AnalyzerDesktop Setting to cdp_OpenFoamPlugin. User can change settings in Ceetron Components 
    based applications that will be set when starting the plugin.

**Version 1.0 [November 27, 2019]**

-   First test version


-------------

All Rights Reserved. No part of this documentation or the accompanying source code shall be reproduced, stored in a 
retrieval system or transmitted by any means without written permission from the publisher.
