System-dependent procedures for installing and running KAPSEL

STEP 1: The KAPSEL runtime environment

The procedure for installing and running KAPSEL depends slightly on whether you are running on a Windows(+Cygwin), Linux, or Mac system:

  • Linux
    If you are using KAPSEL on a Linux system, you may skip to STEP 2 below. In this case you may use either single-core or multi-core executable files.
  • Windows
    To use KAPSEL on a Windows system, you must first install the Cygwin1 package; be sure that your Cygwin installation includes the gcc, make, libfftw3-devel, libhdf5-devel, and libhdf5cpp-11 packages.2 After installing Cygwin, skip to section 2.1.2 below. Only single-core executables may be used on Windows systems. Although Cygwin should be able to run in either 32-bit or 64-bit mode, we recommend using the 64-bit version (setup-x86_64.exe)
  • Mac
    To use KAPSEL on MacOS, you must first install Xcode and the command line tools. For MacOS systems with Intel CPUs, both single-core and multi-core executables may be used. For systems with ARM CPUs, only single-core executables may be used.

STEP 2: Installing OCTA

For tasks such as processing input parameters and visualizing output data, KAPSEL relies on an external user-interface module known as Gourmet. Gourmet is distributed as an internal component of the open-source package OCTA (a universal simulator for soft materials), which must be installed before using KAPSEL. To install OCTA, simply visit to download and run an appropriate installer for your system. The instructions below assume that OCTA8.# has been installed in /usr/local/OCTA8# (for Linux or Mac) or in C:\OCTA8.# (for Windows).

STEP 3: Installing KAPSEL

Download “KAPSEL version 5.00” – Downloaded 1 time – 106 MB

Download the latest version of the KAPSEL distribution package (an archive file named from the above button. Then extract the content of the archive and enter the top-level directory:

$ unzip 
$ cd kapsel#.#

The top-level directory contains the following subdirectories:

  • ./bin/ KAPSEL executable files for various platforms.
  • ./Documents/ User manuals (including this document).
  • ./Examples/ Example calculations illustrating various KAPSEL features.
  • ./UDF/ UDF files (define.udf/input.udf) for using all features in the latest KAPSEL release.

Next, within the ./bin/ directory, find the executable file appropriate for your runtime environment and create a symbolic link in the KAPSEL installation directory.

  • Linux
    • For the single-core executable:
      $ ln -s ./bin/kapsel_linux ./kapsel
    • For the multi-core executable:
$ ln -s ./bin/kapsel_linux_omp ./kapsel
  • Windows
    • For the single-core executable:
      $ ln -s ./bin/kapsel_cygwin ./kapsel
  • Mac (Intel CPU)
    • For the single-core executable:
      $ ln -s ./bin/kapsel_mac_intel ./kapsel
    • For the multi-core executable:
      $ ln -s ./bin/kapsel_mac_intel_omp ./kapsel
  • Mac (Arm CPU)
    • For the single-core executable:
      $ ln -s ./bin/kapsel_mac_arm ./kapsel


cd UDF
../kapsel -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf
#using input.udf as input
#using output.udf as output
#using define.udf as definition
#using restart.udf as restart
#output.udf end.
#restart.udf end.
#Simulation has ended!
#Total Running Time (s):      24.77
#                   (m):       0.41
#                   (h):       0.01
#Average Step Time  (s):       0.02
#                   (m):       0.00
#                   (h):       0.00
  • If you see a command-line output as shown above, KAPSEL has been successfully built and run.
  • The sample input.udf conduct a simulation of sedimenting 5-heavier + 5-lighter particles in Newtonian fluid, which is resolved by a 32x32x32 CFD grids. It takes less than a minute to be completed. If this sample successfully run, “output.udf” will be created.

STEP 5: How to visualize simulation data of KAPSEL

  • You can visualize various simulation data using python script from Gourmet. Simple examples are shown below.
  • Start GOURMET
    • Windows: (OCTA install dir)\GOURMET\gourmet
    • Linux: /usr/local/OCTA8#/GOURMET/gourmet
    • Mac: /usr/local/OCTA8#/GOURMET/src/osxapp/
  • Open “output.udf” (“File” -> “Open” -> Open “output.udf”) [1]
    • Instantaneous positions and velocities of all the particles can be seen as variables in “Particles[]”. Use slide bar at the bottom of GOURMET viewer window to see variables at different time steps.
  • Making an animation on GOURMET
    • Go down to “Python” panel, and click “Load” [2]
    • Open “”, and click “Run” [3]
    • A new window will open, then click the playback button there. [4]

  • Plot data using gnuplot from GOURMET
    • Go down to “Python” panel, and click “Load” [2]
    • Open “”, and click “Run” [3]
    • Go up to “View” box, and check “Table” [4]
    • Go left and select “Graph Sheet[]”. [5]
    • go down to “Plot” panel, and type the following in the command box. [6,7]
plot 'plot.dat' using 2:7 with lines
    • Click “Plot”, then you will see the time evolution of Vx of the 1st particle. [8]

STEP 6: How to analyze simulation data of KAPSEL

  • The history of simulation run (instantaneous positions and velocities of particles) is stored in “output.udf”. One can access to this file by one of the following methods.
    • Python code with “”: Please read the manual below for more general information on accessing UDF using Python.
      • English: pythoninterface_eng.pdf
      • Japanese: PythonInterface_jpn.pdf
      • “” is a sample python script to calculate the static structure factor S(k) from the temporal particle positions stored in “output.udf”. It requires the “numpy” package to handle array variables. You can read and edit the script for your own purposes.
      • For Windows: “Start Menu” > “All Programs” > “OCTA” > “StartGourmetTerm
      • For Linux / Mac: Run “/usr/local/OCTA8#/GOURMET/gourmetterm”
>> plot 'sk.dat' w line
    • Jupyter Notebook with “”: You can do the same thing using Jupyter Notebook (distributed with Anaconda etc…) as follows from bash prompt.
. $PF_FILES/bin/
. $PF_FILES/bin/
jupyter notebook sk.ipynb
    • Fortran or C codes with “libplatform”: Please read the manual below more general information on accessing UDF using Fortran or C.
  • KAPSEL returns several important data to stderr as well (temporal stress etc). It usually appears in command line, but one can redirect stderr to a file as follows.
    • For csh or tcsh
../kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf >& out
    • For sh, bash, or Windows command prompt
../kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf 2> out