QUICKSTART¶
System Requirements¶
KiSSAM requires a workstation with Linux OS and at least one NVidia GPU. The minimal hardware requirements are
x86 CPU (Intel i5 processor or AMD Ryzen 5 desktop or server);
NVidia GPU Ampere or newer architecture with more than 16 GB GPU memory;
RAM 32 GB RAM.
Software requirements
Ubuntu 22.04+
X server (recommended)
NVidia latest driver
NVidia CUDA toolkit (ver. 12 is preferable)
Python 3.10+
numpy
python pillow (recommended)
GLut library (libglut 3 or freeglut3 package) (recommended);
VirtualGL (recommended);
OpenVDB library (recommended).
Recommended third party software
A text editor or JSON editor for configuration.
vdb_view
or Blender for viewing output geometry.Preferred data analysis software: MS Excel, Matlab, etc.
Installation and Setup¶
Please contact our support team for the setup of the KiSSAM package on your system.
Quickstart¶
KiSSAM is run from Linux terminal.
The starting script and default simulation setup file
start_calc.sh
and
default.json
are provided with the distribution.
Open terminal and make calculation directory
> mkdir my_calc
> cd my_calc
Create the input JSON file. The minimal JSON file has to contain the information on the license.
> echo {"licenseFile": "my-license-file.lic"} > input.json
Run the simulation startup script with the input file
> INPUT_JSON_FILE=input.json /opt/KiSSAM/start_calc.sh
Simulation is started with the default parameters. The parameters of the simulation are specified in this input JSON file. You can get the examples from User Cases and refer to the JSON specification for the details. Alternatively, you can copy the default JSON file and edit it: change the relevant fields and erase irrelevant fields.
The free GPU will be chosen automatically.
If all GPUs on the computer are busy, it may not start.
You can use --wait
option.
It makes the startup script wait until any GPU is released and do not return control in terminal.
> INPUT_JSON_FILE=input.json /opt/KiSSAM/start_calc.sh --wait &>log &
To check that the stratup is successful, confirm that
no errors are output in the terminal
*.log
files are generated.computation can be confirmed by the
nvidia-smi
terminal command
kissam-log-x.log
contains simulation log. x
is the incremental file number. It is updated during the simulation.
If the lines of the following type are appearing continuously, the simulation is being successfully executed in the background.
--+-- Iteration 0 --+-- virtual time 0.000 milliseconds
PIDXXXXXX.log
(XXXXXX
is the process ID of the simulation) is a symbolic link to the kissam-log-x.log
.
The simulation will end when the maximal number of steps is reached (can be changed in the JSON file), or can be interrupted with the kill
command in terminal.
To end simulation before it is finished
> kill -9 XXXXXX
Expected simulation time is several hours. Check the process during the simulation by looking at the output files.
Output¶
By default the output result is in the output
directory (can be changed in the JSON file).
full_params.json
records all the parameters of the simulation, inluding both user specified and the default parameters, and the KiSSAM version as well.Warning
Even though it is a JSON file, it should never be used for the input of a simulation. Using it as an input file may cause errors that are difficult to track. To prevent such errors, the JSON syntax in it is broken on purpose.
init_geometry.vdb
is the initial geometry (powder+substrate) of the powder bed. OpenVDB is a library and file format for the interoperability and storage of volumetric data, and it is supported by various 3D software. The file contains two grids with the following names:FillingFrac
, typefloat
, is the filling fraction of mesh cells;ParticleIds
, typeInt32
, are identifiers which help to distinguish types of solid: powder particles, substrate, melted material.
Note that the cells are not activated in this output, so third party software may not render it.
A script to activate the cells for visualization is provided with the software.
The file metadata includes all input parameters of the simulation.
* geometry.vdb
is the latest geometry computed in the simulation.
The file also contains both FillingFrac
and ParticleIds
grids plus full metadata.
If the geometry was written while the simulation is in progress and melt is not solidified yet, the grids named Temperature
and Velocity
represent corresponding parameters in the melt pool region.
Note that here the temperature is written only on the meltpool region. The temperature in the whole simulation region is written in the VTK file Temp.vtk
.
![vdb image](../_images/vdb2blender.png)
Fig. 1 Example of the vdb file loaded and rendered in Blender. Surface of a single track on a bare substrate¶
rendered3D/
is a directory with rendered 3D views of the simulation.
Only a part of the grid, centered around the laser incidence point, is shown. The visualization box moves with the laser. The size of visualized area can bet changed in the JSON file. The rendered image inside the box shows only the Meltpool~Grid: a domain for fluid dynamics simulation of adaptive size that contains the meltpool.
![rendered3D image](../_images/rendered3d.png)
Fig. 2 Example of the rendered 3D image in the output¶
cross-sections/
is a directory with PNG images with 2D cross-sections of meltpool grid in different positions.
It contains subdirectories with names X*****
, which contain cross sections at \(x=\)*****
(in μm) and Y*****
, which contain cross sections at \(y=\)*****
.
The images inside are named sec-itt.png
: the cross sections in the specified position at times \(t=\)t
.
The meltpool grid is adaptive, therefore, cross-section images have different sizes, and may be empty if the section does not intersect the meltpool grid at the moment. KiSSAM includes utility scripts that combine the images and pad them so that sizes match and generate informative animations.
![Cross Section image](../_images/sec-it000105000.png)
Fig. 3 Example of cross-section in the output. Yellow grid lines show 100 μm scale.¶
Use the pad_images.sh
script to pad images.
palletes_raw.png
,palettes_crop.png
– images of color maps used for visualizations.
Three separated color scales are used for liquid, for solidified material and for solid that was not melted. The temperature range is from 0K to 3000K. The palette depends on the material properties, namely, melting and solidification temperatures.
![]() |
![]() Fig. 4 Colormap images output in the code¶ |
entalpy_diagnostics.log
– logfile for material temperature-dependent enthalpy. This log is used to verify correct usage of theMaterial.HeatCapacityVolVals
andMaterial.HeatCapacityRefTemp
parameters.Temp.vtk
— the binary VTK.vtr
files (VTK rectilinear grid) with global temperature distribution and tractile grid cell fractions.outTprobes.dat
– text files with temperature in probes with coordinates specified in input filemyTprobes.dat
.
The file contains a table with a column for each probe and a row for each time iteration. The first column is an iteration number.
meltpoolStats.dat
— text file with time-dependent meltpool depth, height and width.
To get these dimensions, the fluid cells with maximal/minimal \(x\), \(y\), and \(z\) coordinates are found, as well as maximal/minimal \(x\), \(y\) at the level of substrate. From these values, the meltpool dimensions are estimated.
absorbedEnergy.dat
— time-dependent absorbed energy by solid and liquid phases.
What’s next¶
Refer to the user cases provided with the software. We recommend to run the user cases to get more experience with KiSSAM usage.