 |
Documentation for OpenFLUID
2.2.2
|
|
Documentation for OpenFLUID
2.2.2
|
In OpenFLUID since version 2.2.2, a ware set is a group of simulators and observers for which we do coordinate operations. The most frequent use case is the rebuild of setup to run a given dataset.
Back in OpenFLUDI 2.1 days, it was aready possible to do group operations on wares, either to fetch them from a remote location with import dialog or to operate locally for configuration/build/doc generation with dashboard.
Since 2.2.2 it is possible to make these group operations easier: in DevStudio ware import dialog, once connected to a Hub instance, it is possible to select wares via a file instead of picking them one by one. The file can be either a lock json file (cf "Wareset lock file" section below) or a basic text file. The format of such file is very straightforward:
In this example two wares will be selected in the list, foo and bar, for the second one the openfluid2.1-custom branch will be checked out after fetch of the given git URL. Notice that the /local/path will be ignored since the wares will be stored in the current workspace in the corresponding ware category folder.
Once the wares are selected, the import can be triggered as before, but an option has been added to open the Dashboard with the same selected wares (if successfully imported) to run any Dashboard operation.
For more customization and advanced operations about these groups of wares, we advise to use CLI command described in next section instead of relying on DevStudio features.
Since most information required to rebuild a simulation environment is contained in the fluidx files (enabled simulators and obsevers), we can use it to rebuild from scratch all these wares.
A simple use case: we want to rerun Firespread example dataset in an isolated environment. To do so we can call: openfluid setup-wareset -w https://hub.openfluid-project.org/api/ -s ~/.openfluid/examples/projects/Firespread/IN/ -p /tmp/NEW_LOCATION -r.
-w: ware source, can be:-s: "set" list information, can be:-p: path to new location to build the new userdata path (isolated workspace and wares folders)-r: to run simulation after buildFor information about other arguments, call openfluid setup-wareset -h.
A wareset-setup.json file can be added in the IN to provide complementary information about:
-w value)To be connected to the fluidx information, each ware require both information: id and type.
For information identical to all wares, a group with "id": "*" can be added, which will be propagated to all effective wares.
Example:
In this example the setup will create two simulator repositories. For the first it will checkout the version from common section ("*"), for the second this value is overwritten so it will checkout the "for-test" branch.
For each ware:
wares folderGlobal:
wareset-lock file at the root of the location provided in -p parameterAs shown in the example, several placeholders can be used inside the wareset-setup.json file:
On program side:
%OF%%, will be replaced by the openfluid binary locationOn arguments side:
%BuildParent%% will be replaced by either workspace path or ware path, useful for file manipulation in build context%WarePath%% will be replaced by the absolute ware path%WorkspacePath%% will be replaced by the absolute isolated workspace path%FOO%%: the command will try to convert any variable between %%, here FOO, if it exists as environment variable in the command contextOption -m allows for shared configuration and compilation of all wares, leveraging cmake capabilities to optimize compute resources (option -j <N> to define the number of parallel jobs to be run).
Pro: can be way faster to operate and run steps than sequential build
Cons: if a step fails, it will be harder to know which ware had an issue
If this option is active, several files will be added in wares-dev folder to provide a "model-level" CMake structure:
CMakeLists.txt with necessary options for multi-ware buildCMake.wareset.in.config listing folders of each ware_build folder will be created in which the operations will be done.-m option, making each ware compilation isolated.This strategy will allow you to do common actions on all wares when in the shared _build folder: reconfigure all wares, build them, apply any common target like make docalyze to generate documentation of each one or ctest to run all tests in these wares (problematic if several wares have a test with the same name)
Once the wareset setup is done, operations can be done at global level or at ware level and still use the CMake customization that is stored in a CMake.contextual.in.config file.
If you create a _build folder at ware level, by default a compilation will ighore the contextual CMake file to get the default environment. You can activate the contextual CMake by adding the option CUSTOM_VARS during cmake call: cmake .. -DCUSTOM_VARS=ON.
Any time the command setup-wareset is called, a wareset-lock.json file is generated, containing precise information about each ware (when available):
wareset-setup.json file (both direct and from common block)This file can be used instead of a dataset as input for -s option, to get a snapshot of version for the environment as a form of reproductibility, even if not absolute.
Or any folder following .openfluid structure.
For memory, here is what contains a .openfluid folder:
The isolated folder generated by setup-wareset command will have the same structure.
The main resources you may want to move to your .openfluid are ware soure code and binaries of compiled wares. OpenFLUID does not provide an automatic method to move them but you can use them or copy them manually:
OPENFLUID_USERDATA_PATH=/path/to/isolated/folder openfluid-builder.openfluid/wares you will be able to use them with OpenFLUID (not advised since it will decorrelate the workspace content and the wares binaries and may erase valuable binaries) 
1.9.8