Logo for OpenCMISS.
Search box for documentation and more.

Welcome to the OpenCMISS software suite documentation!

We have two major groups of people using OpenCMISS:

Users:They use the OpenCMISS components to run, create and modify applications and examples.
Developers:These folks intend to make changes to the OpenCMISS library codebase itself, i.e. add functionality to Iron, Zinc or any other component.

Consequently, if you are new to OpenCMISS and want to get familiar with it or you already have a certain application in mind, you should start with the OpenCMISS User instructions. If you have a more involved project at hand or you already know that you will end up adding functionality to OpenCMISS components, the OpenCMISS Developer instructions are the right place to start.

OpenCMISS User instructions

Downloading binary packages is a good place to start to get to know OpenCMISS. If you are a user without programming experience, you should start with Using OpenCMISS via Neon. If you have some experience with programming and want to use the OpenCMISS libraries via its offered bindings, you should have a look at Using the OpenCMISS User SDK.

Using OpenCMISS via Neon

Using the OpenCMISS User SDK

The User SDK provides pre-compiled binaries of all OpenCMISS main libraries and can be used to develop own applications against them using either the directly exposed APIs or provided bindings to C or Python languages. Check the downloads section for current packages.

In addition to the SDK, you need a local MPI installation if you want to run parallel code with OpenCMISS-Iron.

For an example using Fortran, C and Python bindings see the Resources/Examples folder within the installation directory of the User SDK.

As the use is different depending on the intended API, please see the appropriate sections below.

Using the Fortran API or C bindings

We recommend to use CMake to develop OpenCMISS applications (OpenCMISS itself is built by CMake), of which you need version 3.4 or newer. Instructions for other ways of using the installed SDK libraries in your development environment will be added later. Essentially, all you need to do is add the Resources/OpenCMISS.cmake file from the SDK installation directory to your example project and include that before you issue the project(..) command. After your project command, you can use the find_package(OpenCMISS ..) command to find and prepare use of OpenCMISS in your application. An exemplary CMakeLists.txt could look like:

# This is my OpenCMISS application

include(./OpenCMISS.cmake)

cmake_minimum_required(VERSION 3.4)
project(MyOpenCMISSApplication LANGUAGES C Fortran)

[...]

find_package(OpenCMISS <VERSION> REQUIRED COMPONENTS [Iron|Zinc] CONFIG)

This will look for an OpenCMISS package information, which is contained in your User SDK installation. It will also verify that the found User SDK in fact matches your locally configure toolchain and mpi choice. Then, to add OpenCMISS-powered libraries and executables, use:

# For a library use
add_library(mylib <SOURCES>)
target_link_libraries(mylib PRIVATE opencmiss)

# For an executable use
add_executable(myexec <SOURCES>)
target_link_libraries(mylib PRIVATE opencmiss)

If you wanted to add a test for your binaries/libraries, you can conveniently use:

# Add a test that runs your binary
add_test(myapptest myexec)
add_opencmiss_environment(myapptest)

The add_opencmiss_environment function will set up the test environment to contain the necessary library paths. The testing can then be run using CTest

Finally, to configure your application, you need to set the variable OPENCMISS_SDK_DIR to your User SDK installation folder in CMake (define in CMake-GUI or set via -DOPENCMISS_SDK_DIR in command line).

Note

If suitable, you may also define the OPENCMISS_SDK_DIR variable in your environment. This way you dont have to specify it when configuring your own component builds through CMake/manage. Windows only If you chose the default install location, CMake can pick up the installation via system default paths and you dont have to specify anything!

For an CMake-enabled example using Fortran and C see the Resources/Examples/classicalfield_laplace_simple example within the installation directory.

Using the Python bindings

The currently available User SDKs come with Python bindings built with Python 2.7.11 (x64). We aim to provide other versions in the future.

You will need to install:

If you intend to use virtual environments, make sure to activate your target environment before proceeding with the following installation steps.

To install the Python bindings, open a command prompt and type:

pip install <USERSDK_DIR>/<ARCHPATH>/python/(Release|Debug)

Here, USERSDK_DIR is the installation root of your SDK, ARCHPATH is the sub-path matching your current environment, and (Release|Debug) refers to the build type. For the current Windows User SDK, this path could be e.g.:

pip install <USERSDK_DIR>/AMD64_Windows/msvc-18.0-F15.0/mpich2_release/python/Release

for Iron Python bindings or:

pip install <USERSDK_DIR>/AMD64_Windows/msvc-18.0-F15.0/no_mpi/python/Release

for Zinc bindings (Zinc does not need MPI and will always be located within no_mpi).

Building everything from source

As a OpenCMISS user, you should not really have to build the entire OpenCMISS software suite - the Neon frontend and User SDK should get you going in most scenarios. However, if we don’t have the pre-built binaries for your scenario (e.g. you are maintaining a computational cluster), you will need to build the OpenCMISS suite from source.

OpenCMISS Developer instructions

Depending on the scenario at hand, there are two options for OpenCMISS developers. If you intend to modify the OpenCMISS main components but wont need to fuddle with any of the dependencies, the Using the Developer SDK is probably the most convenient way to achieve this. If you need to modify some of the dependencies (experienced programmers only), you will have to stick with Building OpenCMISS from source.

Using the Developer SDK

Check the downloads section for current packages.

Once you’ve installed the developer SDK, you can essentially follow the steps at Building the OpenCMISS Suite with the following addition: You need to set the variable OPENCMISS_SDK_DIR to your Developer SDK installation folder in CMake (define in CMake-GUI or set via -DOPENCMISS_SDK_DIR in command line).

Then, the main build script will simply pick up the matching pre-installed components instead of building them! :-)

Attention

The manage script always compiles the current architecture path for your build selection and tries to find the corresponding pre-build libraries at the same sub-path within the Developer SDK. If that path cannot be found, an error is issued and you should check if your current selection (toolchain, mpi type, build type..) is contained in/supported by the SDK.

Note

If suitable, you may also define the OPENCMISS_SDK_DIR variable in your environment. This way you dont have to specify it when configuring your own component builds through CMake/manage.