Quick Start

This tool has been compiled and tested on Windows (x86_64, ARM64), Linux (x86_64, ARM64), and macOS (x86_64, Apple Silicon). Using any other architecture is not guaranteed to work.

Download#

To run COMFOR, you can download the binaries from the release page or you can build it from source. Download the binary for your architecture, follow the instructions given here, and run some tests.

To build COMFOR from sources, you will need to download and compile the code. If so, follow the instructions below.

Build from sources#

Prerequisites#

CMake: A cross-platform, open-source build system generator. It allows you to generate a project for a given IDE (Unix Makefiles, Xcode, Visual Studio, etc.) or compilation rules for COMFOR. It can be easily installed under Linux with the following command:

sudo apt install cmake

On macOS using brew:

brew install cmake

Binary files for macOS and Windows can be downloaded at cmake.org.

C++ Compiler

COMFOR is written in C++ and requires a C++ compiler that supports C++17 features or higher.

Recommended versions:

GCC >= 11
Clang >= 14
Apple Clang >= 13.0.0
MSVC >= 2022

Under Ubuntu 22.04 / 24.04 LTS, you can install the necessary tools with:

sudo apt install build-essential

Under macOS, verify if the Clang compiler is already installed:

clang --version

To install or update the Clang compilers, enter:

command xcode-select --install

Under Windows, you can use a POSIX environment like MSYS2 or MinGW-w64. COMFOR is also fully compatible with Microsoft C++ compilers (Tested using Visual Studio 2022).

Warning

Some versions of MinGW may have compatibility issues with google-test (see issue 2418). While you can compile COMFOR, building the unit tests might require specific configurations.

Python

Note

Python is mainly used for result post-processing, automated testing, and generating this documentation.

Make sure Python 3.10+ and the following packages are installed:

Charts: Matplotlib
Documentation: MkDocs-Material

Install the packages using pip:

python3 -m pip install matplotlib mkdocs-material

Warning

On Windows, it is recommended to use the standalone Python.org distribution. Ensure that python and pip are added to your system PATH.

Clone#

Clone or download the sources from the main repo.

git clone https://gitlab.com/comfor/comfor.git

Compile#

Using CMake (Recommended)#

The compilation rules are generated by CMake using the CMakeLists.txt file included in the project. A good habit is to encapsulate all intermediate files in a single folder (the build). CMake identifies the architecture and generates the project rules.

cd COMFOR
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release

The binary files will be located in the bin/Release folder.

Tip

CMake can generate projects for different IDEs (Visual Studio, Xcode, Eclipse). You can specify a generator using cmake .. -G <generator_name>. To see the available list for your system, use cmake -G.

Cross-platform proposition#

If you prefer a graphical interface, you can use Visual Studio Code with the "C/C++" and "CMake Tools" extensions to automate the compilation process.

Execution Options (CLI)#

COMFOR is a command-line tool. You can control its behavior using various arguments to manage parallel execution, validate files, or display software information.

Available Arguments#

Argument	Long Form	Value	Description
`-j`	`--job`	`FILE`	Required. Path to the input file (`.toml`, `.txt` or `.fembic`).
`-u`	`--cpus`	`1..16`	Number of CPU threads for parallel execution. (Default: `1`).
-	`--validate`	-	Validates the input file syntax without running the solver.
`-i`	`--info`	-	Shows general information about COMFOR.
`-c`	`--credits`	-	Lists software contributors and libraries.
`-l`	`--license`	-	Displays the software license terms.
`-v`	`--version`	-	Shows the current version.
`-h`	`--help`	-	Prints the help message.

Run and test#

You should now have an executable file called COMFOR (or comfor.exe on Windows).

Run it#

To launch a simulation, navigate to your work directory and use the -j (or --job) flag followed by your input file. You can also specify the number of CPU threads with -u.

# Standard execution (1 thread)
./comfor -j Examples/input_file.toml

# Parallel execution with 4 threads
./comfor -j Examples/input_file.toml -u 4

Tip

If you run ./comfor without the -j argument, the program will start in interactive mode and prompt you to manually type the path to your input file.

Validate it#

If you want to check your input file for syntax errors or missing parameters without starting the actual computation, use the --validate flag:

./comfor -j Examples/input_file.toml --validate

Test it#

In addition to the main binary, CMake generates a series of test executables (e.g., AmplitudeTest, MaterialTest). These allow you to verify if the different COMFOR modules are working correctly on your machine.

Example:

./AmplitudeTest

Expected result:

[==========] Running 5 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 5 tests from TabularTest
[ RUN      ] TabularTest.parseOne
[       OK ] TabularTest.parseOne (0 ms)
...
[  PASSED  ] 5 tests.

Postprocessing#

COMFOR generates VTU or VTK files for the results. ParaView is the recommended open-source post-processor to visualize these results. ParaView is available at paraview.org.