Step-by-step instructions to install KAPSEL

STEP 0: System requirements to use KAPSEL

  • Windows (+ Cygwin) / Linux / Mac

    • The following description assumes that you are working as the root user. When working with a user account that has administrative rights, use the sudo command as appropriate.

    • To use KAPSEL on Linux, go to STEP 1.
    • To use KAPSEL on Windows, install “Cygwin” first, then go to STEP 1. In the Select Package section, set View “Category” and be sure to include the following Packages.
      • all Packages in the Devel category
      • all Packages related to fftw3 in the Libs category
      • all Packages related to hdf5 in the Libs category
      • python3 Package in the Python category
  • Gnu C++ Compiler
  • Intel C++ Compiler (Intel oneAPI Toolkits)
  • OCTA
  • FFTW
  • HDF5
  • LIS (optional)
  • KAPSEL (source codes and examples)

STEP 1: Install OCTA

  • Visit OCTA-HP and download an appropriate installer of OCTA.
  • Install OCTA, usually just by running the installer. Please be a member of OCTA-BBS if you have any questions about OCTA/GOURMET.
  • In the following STEPS, we assume that OCTA8.4 is installed in /usr/local/OCTA84 (Linux/Mac) or C:\OCTA8.4 (Windows). Replace “8.4” or “84” with an appropriate version number of OCTA.

STEP 2: Build libplatform

  • “libplatform” is an I/O library used by OCTA to access data stored in UDF-formatted files.
  • You may have to install additional software such as OpenJDK8 [AdoptOpenJDK: https://adoptopenjdk.net / For arm64 (Apple silicon): https://www.azul.com/downloads/] and Python3 [Anaconda] to build libplatform depending on your environment.
  • For Windows:
    • Logon Windows with an administrator authorization
    • Open Cygwin terminal window
ln -s /cygdrive/c/OCTA8.4 /usr/local/OCTA84 (without ".")
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure --with-python
make
make install
mv ../lib/cygwin/libplatform.a ../lib/cygwin/libplatform_gcc.a
  • For Linux:
    • with gcc
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure --with-python
make
make install
mv ../lib/linux_64/libplatform.a ../lib/linux_64/libplatform_gcc.a
    • with icc
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure CC=icc CXX=icpc --with-python
make
make install
mv ../lib/linux_64/libplatform.a ../lib/linux_64/libplatform_icc.a
  • For Mac:
    • with clang (default C compiler of macOS)
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure CC=clang CXX=clang++ --with-python
make
make install
mv ../lib/macosx/libplatform.a ../lib/macosx/libplatform_clang.a
    • with gcc (ex. “brew install gcc-12”)
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure CC=gcc-12 CXX=g++-12 --with-python
make
make install
mv ../lib/macosx/libplatform.a ../lib/macosx/libplatform_gcc.a
    • with icc
cd /usr/local/OCTA84/GOURMET/src
make distclean; make clean
./configure CC=icc CXX=icpc --with-python
make
make install
mv ../lib/macosx/libplatform.a ../lib/macosx/libplatform_icc.a
  • In some cases, GOURMET doesn’t start properly after building libplatform. Please execute one of the following commands if this happens.

cd /usr/local/OCTA84/GOURMET
./Make-All.sh

cd /usr/local/OCTA84/GOURMET/src
sudo ./build-gourmet

STEP 3: Install FFTW

  • For Windows
    • Need nothing
  • For Linux
    • Download source codes and install them manually
      • with gcc
./configure --prefix=/opt/fftw/latest.gcc CFLAGS="-O3" FFLAGS="-O3" --enable-openmp --enable-threads --enable-shared --disable-fortran
make
make install
      • with icc
./configure --prefix=/opt/fftw/latest.icc CC=icc CXX=icpc CFLAGS="-O3" FFLAGS="-O3" --enable-openmp --enable-threads --enable-shared --disable-fortran
make
make install
  • For Mac
    • Install “fftw3” using Homebrew (for clang and gcc compilers)
brew install fftw
    • Download source codes and install them manually
      • with gcc
./configure --prefix=/opt/fftw/latest.gcc CC=gcc-12 CXX=g++-12 CFLAGS="-O3" FFLAGS="-O3" --enable-openmp --enable-threads --enable-shared --disable-fortran
make
make install
      • with icc
./configure --prefix=/opt/fftw/latest.icc CC=icc CXX=icpc CFLAGS="-O3" FFLAGS="-O3" --enable-openmp --enable-threads --enable-shared --disable-fortran
make
make install

STEP 4: Install HDF5

  • For Windows
    • Need nothing
  • For Linux
    • Download source codes and install them manually
      • with gcc
./configure --prefix=/opt/hdf5/latest.gcc CFLAGS="-O3" FFLAGS="-O3" --disable-fortran --enable-cxx
make
make install
      • with icc
./configure --prefix=/opt/hdf5/latest.icc CC=icc CXX=icpc --disable-fortran --enable-cxx
make
make install
  • For Mac
    • Install “hdf5” using Homebrew (for clang and gcc compilers)
brew install hdf5
    • Download source codes and install manually
      • with gcc
./configure --prefix=/opt/hdf5/latest.gcc CC=gcc-12 CXX=g++-12 --disable-fortran --enable-cxx
make
make install
      • with icc
./configure --prefix=/opt/hdf5/latest.icc CC=icc CXX=icpc --disable-fortran --enable-cxx
make
make install

STEP 5: Install LIS (optional, can be skipped now)

  • For Windows
    • Download source codes and install them manually
./configure
make
make install
  • For Linux
    • Download source codes and install them manually
      • with gcc
./configure --prefix=/opt/lis/latest.gcc
make
make install
      • with icc
./configure --prefix=/opt/lis/latest.icc CC=icc CXX=icpc 
make
make install
  • For Mac
    • Download source codes and install them manually
      • with clang
./configure --prefix=/opt/lis/latest.clang CC=clang CXX=clang++
make
make install
      • with gcc
./configure --prefix=/opt/lis/latest.gcc CC=gcc-12 CXX=g++-12
make
make install
      • with icc
./configure --prefix=/opt/lis/latest.icc CC=icc CXX=icpc
make
make install

STEP 6: Build KAPSEL executables

  • Download the latest version of KAPSEL source codes & examples (kapsel4.30.zip). Replace “4.30” with an appropriate version number.
unzip kapsel4.30.zip
cd kapsel4.30/src
  • You may modify GOURMET_HOME_PATH in the attached “Makefile” so that the library “libplatform.a” is correctly linked. Also modify -I(include file path) and -L(library file path) appropriately for your environment.
  • Clean-up working files first.
make clean
  • Build a KAPSEL binary executable appropriate for your environment by one of the following make commands.
  • For Windows
    • with cygwin

make ENV=CYGWIN_OMP FFT=FFTW

  • For Linux
    • with gcc

source scl_source enable devtoolset-11

make ENV=GCC_OMP FFT=FFTW

    • with icc

source /opt/intel/oneapi/setvars.sh

make ENV=ICC_OMP FFT=IMKL

  • For Mac
    • with clang

make ENV=CLANG_OMP FFT=FFTW

    • with gcc

make ENV=GCC_MAC_OMP FFT=FFTW

    • with icc

source /opt/intel/oneapi/setvars.sh

make ENV=ICC_MAC_OMP FFT=IMKL



STEP 7: Run KAPSEL


    

  • For Linux

      

    • with gcc
      • 

    

    • 



export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/hdf5/latest.gcc/lib:/opt/fftw/latest.gcc/lib:/opt/lis/latest.gcc/lib


    

  • 

      

    • with ICC
      • 

    

    • 



export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/hdf5/latest.icc/lib:/opt/fftw/latest.icc/lib:/opt/lis/latest.icc/lib


    

  • For Mac

      

    • with clang
      • 

    

    • 



export DYLD_LIBRARY_PATH=”/usr/local/homebrew/lib:/opt/lis/latest.clang:DYLD_LIBRARY_PATH”


    

  • 

      

    • with gcc
      • 

    

    • 



export DYLD_LIBRARY_PATH=”/opt/fftw/latest.icc/lib:/opt/hdf5/latest.icc/lib:/opt/lis/latest.icc/lib:DYLD_LIBRARY_PATH”


    

  • 

      

    • with icc
      • 

    

    • 



export DYLD_LIBRARY_PATH=”/opt/fftw/latest.gcc/lib:/opt/hdf5/latest.gcc/lib:/opt/lis/latest.gcc/lib:DYLD_LIBRARY_PATH”


    

  • For all
    • 



cd ../UDF
../src/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 8: 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/OCTA84/GOURMET/gourmet
      • 

    • Mac: /usr/local/OCTA84/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 9: 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/OCTA84/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
      • 

    

    • 



../src/kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf >& out


    

  • 

      

    • For sh, bash, or Windows command prompt
      • 

    

    • 



../src/kapsel  -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf 2> out