Step-by-step instructions to install & run KAPSEL

What you need to use KAPSEL

  • Windows + Cygwin* or Linux (*Cygwin 64-bit will work fine, but if not, use Cygwin 32-bit instead.)
  • gcc and make
  • GOURMET (included in OCTA distribution package)
  • KAPSEL source codes & examples
    • kapsel3.33.zip [2018/02/09] Compatible with OCTA8.3 with Python3
    • &ref(): File not found: "kapsel3.32.zip" at page "Install"; [2017/04/04]
    • &ref(): File not found: "kapsel3.31.zip" at page "Install"; [2016/01/27]
    • &ref(): File not found: "kapsel3.30.zip" at page "Install"; [2015/11/09]
    • &ref(): File not found: "kapsel3.20.zip" at page "Install"; [2015/01/19]
    • &ref(): File not found: "kapsel3.12b.zip" at page "Install"; [2014/10/21] (NOTE: fixes bug in v3.12)] Docs for For HDF-5 and Paraview: filekapsel_3.1.pdf fileparaview_howto.pdf
    • &ref(): File not found: "kapsel3.07.zip" at page "Install"; [2013/11/13]
    • &ref(): File not found: "kapsel3.06.zip" at page "Install"; [2013/07/03]
    • &ref(): File not found: "kapsel3.05.zip" at page "Install"; [2013/06/17]
    • &ref(): File not found: "kapsel3.04.zip" at page "Install"; [2013/06/15]
    • &ref(): File not found: "kapsel3.03.zip" at page "Install"; [2013/06/12]

STEP 0: Linux or Windows?

  • To build KAPSEL on Linux, goto STEP 1.
  • To build KAPSEL on Windows, install "Cygwin" first, then goto STEP 1. Be sure to include "gcc", "make" (both exist under "Devel" tree). Both 32-bit and 64-bit cygwin should work fine.
  • KAPSEL can be build also on Mac OS-X. (not officially supported)

STEP 1: Download and install OCTA/GOURMET

  • Visit OCTA-BBS and Download an appropriate version of KAPSEL installation package. Please contact us [kapsel.dev@gmail.com] if any troubles take place.
  • In the following STEPS, OCTA8.# is assumed to be installed in /usr/local/OCTA8# (Linux) or C:\OCTA8.# (Windows).

STEP 2: Build "libplatform"

  • "libplatform" is an I/O library developed by OCTA project. One needs this library to access to UDF-formatted files.
  • For Linux:
   > su
   > cd /usr/local/OCTA8#/GOURMET/src
   > ./configure
   > make
   > make install
  • For Windows:
    • Logon Windows with an administrator authorization
    • Open Cygwin terminal window
   $ ln -s /cygdrive/c/OCTA8.#/ /usr/local/.
   $ cd /usr/local/OCTA8.#/GOURMET/src
   $ ./configure
   $ make (in case of error, make CCOPT=)
   $ make install

STEP 3: Download "KAPSEL" source code

  • You can download KAPSEL source codes & examples at the top of this page.

STEP 4: Build "KAPSEL" binary executable

   > unzip kapsel3.*.zip
   > cd kapsel3.*
  • You may modify GOURMET_HOME_PATH in the attached "Makefile" so that the library "libplatform.a" is correctly linked.
   > make 'ENV=CYGWIN'       (Cygwin on Windows)
   or
   > make 'ENV=GCC'          (gcc on Linux)
   or
   > make 'ENV=ICC'          (icc on Linux)
   or
   > make 'ENV=ICC_MKL_OMP'  (icc + MKL + OpenMP on Linux)
   or
   > make clean   (clean-up working files)

STEP 5: Test run

   > 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.

STEP 6: Visualization of simulation data

  • 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. You can visualize various simulation data using python script from Gourmet. Three simple examples are shown below.
  • Common procedure
    • Start GOURMET
    • Open "output.udf" ("File" -> "Open" -> Open "output.udf").
  • Watching variables on Gourmet
    • 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"
    • Open "particleshow.py", and click "Run"
    • A new window will open, then click the playback button there.

gourmet.jpg anime.jpg

  • Using gnuplot on GOURMET
    • Go down to "Python" panel, and click "Load"
    • Open "plot.py", and click "Run"
    • Go up to "View" box, and check "Table"
    • Go left and select "Graph Sheet[]".
    • go down to "Plot" panel, and type the following in the command box.
       > plot 'plot.dat' using 2:7 with lines
    • Click "Plot", then you will see the time evolution of Vx of the 1st particle.

gourmet2.jpg gourmet3.jpg plot.jpg

STEP 7: Analyzing simulation data

  • 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 program. Please read the manual below for more general information on accessing UDF using Python.
    • English: filepythoninterface_eng.pdf
    • Japanese: filePythonInterface_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" > "OCTA2013" > "StartGourmetTerm?"
        > python sk.py
        > gnuplot
         >> plot 'sk.dat' w line
      sk.jpg
  • 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.
  • In case of csh or tcsh
    > ../kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf >& out
  • In case of sh, bash, or Windows command prompt
    # ../kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf 2> out