Installation Guide

Warning

OpenCMP is primarily tested on Linux (Ubuntu 20.04-21.01) and MacOS. The main functionality should work on Windows but users may have issues exporting results to .vtu.

Warning

NGSolve support for the Anaconda Python Distribution is currently experimental, please do not use NGSolve installed in this way with OpenCMP until further notice.

NOTE

• Top-level directory refers to the highest level directory of OpenCMP. I.e., /users/…/opencmp.

Installing OpenCMP

1. Clone the GitHub repository.

2. Install pip3:

   • Linux and WSL (Windows Subsystem for Linux) - Execute sudo apt install python3-pip.

   • macOS - Install Homebrew via terminal. Then brew install python3. This also installs pip3.

   • Windows - We recommend using WSL (Windows Subsystem for Linux).

3. Install the opencmp module from the top-level directory: pip3 install .

   • Install with optional dependencies here.

4. Optionally, run all the unit tests using pytesting from the top-level directory. Note,

   • In order to run the tests, all optional dependencies must be installed.

   • For full information about running the tests see the README.md inside the pytests folder.

5. Go through the tutorials and other examples found in the “examples/” folder.

Custom Commands for OpenCMP

Using OpenCMP

• opencmp can be run using opencmp config instead of python3 -m opencmp config, where config is the name of the configuration file.

Running OpenCMP Unit Tests

• pytesting from the top-level directory runs all the pytests. All optional dependencies must be installed.

Dependencies

Required

• Python 3.7+

Optional

• edt - Needed for the Diffuse Interface Method.

• tabulate - Needed to output results for mesh refinement and polynomial order convergence tests.

• pytest - Needed for the unit tests.

• pytest-xdist - requires pytest. Can distribute tests across multiple CPUs to speed up test execution.

Command (from top-level directory)	Dependencies Installed
pip3 install .[all]	edt tabulate pytest pytest-xdist
pip3 install .[edt]	edt
pip3 install .[tab]	tabulate
pip3 install .[test]	pytest
pip3 install .[test_ext]	pytest pytest-xdist

• To install opencmp with more than one dependency argument: pip3 install .[x,y]

Supplementary Information

WSL (Windows Subsystem for Linux)

• WSL is the recommended platform for native Windows users to use OpenCMP.

• To install WSL, go to the Microsoft Store. Install Ubuntu 20.04 LTS.

• Python 3.7+ should come pre-installed. To check this, execute python3 --version.

Setting up WSL for OpenCMP

• To be able to use the custom commands for OpenCMP, please perform the following.

  • In WSL, execute nano ~/.bashrc

  • At the bottom of the file append the line export PATH="/home/user/.local/bin:$PATH" where user is the username of your WSL unix profile.

  • Press CTRL+S then CTRL+X. Exit WSL and restart the application.

• ngsolve, a required dependency for OpenCMP, has a graphics issue for WSL. To correct this, install a windows manager via sudo apt install ubuntu-desktop

Installing an X Server on WSL

• WSL does not come with GUI (graphical user interface) application support (shortformed an “X server”). To view output plots or any graphical interface, perform the following.

  • Change display variables in WSL.

    • Execute nano ~/.bashrc. At the bottom of the page, append export DISPLAY=$(ip route list default | awk '{print $3}'):0 and export LIBGL_ALWAYS_INDIRECT=1 (on separate lines).

    • Press CTRL+S then CTRL+X. Exit WSL and restart the application.

  • Enable Public Access on your X11 server for Windows. Follow the tutorial here. Be sure to only follow the section “Allow WSL Access via Windows Firewall”.

  • Download VcXsrv. Navigate to C:\Program Files\VcXsrv and open xlaunch.exe.

    • Click Next until “Extra Settings” page. Check the box for “Disable Access Control”.

    • Save the configuration file somewhere useful. Ensure that you run the config.xlaunch file before executing code with any graphical output.