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 with Intel CPU
    If you use KAPSEL on a Linux system, you may skip to STEP 2 below.
  • Windows with Intel CPU
    To use KAPSEL on a Windows system, you must first install Cygwin. After installing Cygwin, skip to STEP 2 below.
  • Mac with Intel or Arm CPU
    If you use KAPSEL on a Mac system (Intel or Arm CPU), you may skip to STEP 2 below.

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 http://octa.jp/ 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” kapsel5.00.zip – Downloaded 1 time – 105.74 MB

After purchasing the valid license [https://kapsel-dns.com/en/contact/], you can download the latest version of the KAPSEL distribution package (an archive file named kapsel#.#.zip) from the above button. Then extract the content of the archive and enter the top-level directory:

$ unzip kapsel#.#.zip 
$ 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
    $ ln -s ./bin/kapsel_linux_intel ./kapsel
  • Windows
    $ ln -s ./bin/kapsel_cygwin_intel ./kapsel
  • Mac (Intel CPU)
    $ ln -s ./bin/kapsel_mac_intel ./kapsel
  • Mac (Arm CPU)
    $ ln -s ./bin/kapsel_mac_arm ./kapsel

STEP 4: Test 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/StartGourmet.app
  • 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 “particleshow.py”, 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 “plot.py”, 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 “UDFManager.py”: Please read the manual below for more general information on accessing UDF using Python.
      • English: pythoninterface_eng.pdf
      • Japanese: PythonInterface_jpn.pdf
      • “sk.py” 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”
python sk.py
gnuplot
>> plot 'sk.dat' w line
    • Jupyter Notebook with “UDFManager.py”: You can do the same thing using Jupyter Notebook (distributed with Anaconda etc…) as follows from bash prompt.
. $PF_FILES/bin/gourmet_profile.sh
. $PF_FILES/bin/platform_env.sh
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