Tutorial †

↑

To perform normal simulation †

  • Obtain an appropriate sample UDF file for your purpose from our examples.
  • Start "Gourmet" and open the UDF file. Modify it for your own purpose and save it as "input.udf".
  • Run KAPSEL as follows. (remove "./" if you use Windows command prompt)
   > ./kapsel -Iinput.udf -Ooutput.udf -Ddefine.udf -Rrestart.udf
  • "-I" option defines the name of UDF file which contains details of simulation (type of simulation, initial conditions, physical and simulation parameters, etc...).
  • "-O" option defines the name of UDF file which contains the results (time-dependent positions and velocities of all the particles, etc...) of the simulation.
  • "-D" option defines the name of UDF file which contains definitions of KAPSEL data dormat. This is common for any simulations.
  • "-R" option defines the name of UDF file which contains values of all dynamical variables at the end of the simulation See "Re-start run" below.
  • Field data (fluid velocities, ionic densitied, etc...) is saved in a subdirectory specified in "input.udf" if "output.AVS" = "on". This requires huge disk space (GB order). No field data is saved if "output.AVS" = "off".
  • Start "Gourmet" and open "output.udf".
    • Instantaneous positions and velocities of all the particles can be seen as variables in "Particles[]". Use slide bar at the bottom of Gourmet window to see variables at different time steps.
    • Load "plot.py" to plot time evolutions of the variables. (See STEP4)
    • Load "particleshow.py" to visualize motions of particles. (See STEP4)
↑

To re-start previous simulation †

  • One can re-start simulations from the end of the previous run.
  • Start "Gourmet", and open "restart.udf"
  • Set "resume.Calculation" = "CONTINUE"
  • Increase "output.Num_step", and save it as "input2.udf"
  • Run KAPSEL as follows. (remove "./" if you use Windows command prompt)
   > ./kapsel -Iinput2.udf -Ooutput2.udf -Ddefine.udf -Rrestart2.udf
↑

To analyze simulation data †

  • The history of simulation run (instantaneous positions and velocities of particles) is stored in "output.udf". One can access it by one of the following methods.
  • Some important data appears in stranded output (command line). One can redirect the output to a file and analyze the data.
↑

UDF file †

  • UDF is a text file. One can browse and edit it using a text editor, but it.can be more easily handled with "Gourmet". See the manuals below for general information on UDF.
  • In the case of UDF for KAPSEL, one must first choose the type of problem you want to simulate by selecting "constitutive_eq" from list below.
    • Navier_Stokes: (sedimentation, diffusion, coagulation)
    • Shear_Navier_Stokes: (rheology, chain in shear flow)
    • Electrolyte: (electrophoresis)
  • See the list below for definitions of all the variables in UDF for KAPSEL.

constitutive_eq: type: {Navier_Stokes, Shear_Navier_Stokes, Electrolyte}

Navier_Stokes

  • DX:
  • RHO:
  • ETA:
  • kBT:
  • alpha_v:
  • alpha_o:

Shear_Navier_Stokes

  • DX:
  • RHO:
  • ETA:
  • kBT:
  • alpha_v:
  • alpha_o:
  • External_field: type: {DC, AC}:
DC
  • shear_rate:
AC
  • shear_rate:

Electrolyte

  • DX:
  • RHO:
  • ETA:
  • kBT:
  • Dielectric_cst:
  • INIT_profile:
  • Add_salt: type: {salt, saltfree}:
salt
  • Valency_positive_ion:
  • Valency_negative_ion:
  • Onsager_coeff_positive_ion:
  • Onsager_coeff_negative_ion:
  • Debye_length:
saltfree
  • Valency_counterion:
  • Onsager_coeff_counterion:
  • Electric_field: type: {ON, OFF}:
    • ON: type: {DC, AC}:
    DC
    • Ex
    • Ey
    • Ez
    AC
    • Ex
    • Ey
    • Ez
    • Frequency

object_type: type: {spherical_particle, chain}

spherical_particle

  • Particle_spec[]
    • Particle_spec[0]
      • Particle_number
      • MASS_RATIO
      • Surface_charge

chain

  • Chain_spec[]
    • Chain_spec[0]
      • Beads_number
      • Chain_number
      • MASS_RATIO
      • Surface_charge

A_XI:

A:

gravity:

  • G:
  • G_direction: {-X, -Y, -Z}

EPSILON:

LJ_powers: {12:6, 24:12, 36:18}

mesh

  • NPX:
  • NPY:
  • NPZ:

time_increment: type: {auto, manual}

auto

  • factor

manual

  • delta_t

switch

  • ROTATION: {ON, OFF}
  • HYDRO_int: {Correct, free draining, squeeze-lubrication and drain}
  • Stokes: {with advection, w/o advection}
  • LJ_truncate: {ON, OFF, NONE}
  • INIT_distribution: type: {uniform_random, random_walk, FCC, BCC, user_specify}
random_walk
  • iteration
user_specify
  • Particles[]
    • Particles[0] 
      - R
  - x: 
  - y: 
  - z: 
- v
  - x: 
  - y: 
  - z:
FIX_CELL
  • x: {ON, OFF}
  • y: {ON, OFF}
  • z: {ON, OFF}

boundary_condition: type: {z_dirichlet, full_periodic}

z_dirichlet

  • wall_velocity_x:
  • wall_velocity_y:
  • wall_velocity_z:

output

  • GTS:
  • Num_snap:
  • AVS: {ON, OFF}
ON
  • Out_dir:
  • Out_name:
  • File_Type: {BINARY, ASCII}
  • UDF: {ON, OFF}

E:

t:

Particles[]

  • Particles[] 
    - R
  - x: 
  - y: 
  - z: 
- v
 - x: 
 - y: 
 - z:

resume

  • Calculation: {NEW, CONTINUE}