Turbulence simulator V6

This is a simple GUI tool to demonstrate the turbulence simulator. CPU version is available for now. A demo for GPU support is under development.

Download link:

Windows GUI download link: installer | zipped executable

Linux GUI download link: installer | zipped executable

Linux CLI download link: zipped executable | docker image

Note: since the program relies on a specific libtorch distribution, the corresponding dynamic library is included with the simulator. That makes the file size relatively large (~100 MB for CPU and 1.6GB for GPU).

Quick user guide:

If you prefer the installer version, download the .exe installer and follow the instructions. It will ask generic questions like where you want to install the program, etc. If you want to use the zip archive, download it, extract all the files, and run SimGUI.exe.

The interface allows you to choose one or several images using these two buttons:

After loading images, you can run the simulator by File -> Run Simulator or by clicking this button:

Note that you can abort the operation anytime by using File -> Abort Simulator. To change the simulation settings, click File -> Parameters:

You can both change the main parameters as well as the numerical settings like precision and device (the CUDA option is available only on the GPU-enabled version):

Experimanetal CLI tool

As the current version of GUI is only running on Windows, we also provide a simplified CLI linux version that can be used on GUI-less systems. This version supports GPU inference, so the file size is quite large. Please download the corresponding file here.

Usage

First of all, you need to specify all the paramters in the json file. An example default_params.json is provided:

{
    "img_shape": [
        720,
        1280
    ],
    "D": 0.10714285714285715,
    "wvl": 5.5e-07,
    "f": 0.6,
    "L": 600,
    "num_zern": 36,
    "kernel_size": 67,
    "width": 4,
    "anti_aliasing_range": 3,
    "Cn2": 9.9999998245167e-14,
    "batch_size": 1,
    "temp_corr": 0.9,
}

Here is a quick description of the parameters:

- 'img_shape': The size of the input image (height, width)
- 'D': Aperture diameter (meters)
- 'wvl': Wavelength (meters)
- 'f': Focal length (meters)
- 'L': Propagation distance (meters)
- 'num_zern': Number of Zernikes to be used (36 only, don't change)
- 'kernel_size': The kernel size for blurry effect (don't change)
- 'width': Width of real scene of the image in meters
- 'anti_aliasing_range': Range of real scene of the image that ensures no aliasing (meters)
- 'Cn2': Turbulence strength
- 'batch_size': Batch size on the input images
- 'temp_corr': A value in (0, 1), ~1 is a lot of correlation, ~0 is none

Example usage: ./run.sh ../img/ ../out/ ../default_params.json 0,1 > output.txt

Here, we are using GPU devices 0 and 1 for processing. If you only want to use the CPU, just remove the last argument: ./run.sh ../img/ ../out/ ../default_params.json > output.txt

The simulator is quite demanding in GPU memory, for instance to run a 720x1080 image with batch size 1 we need ~13GB of memory for efficient compute. If you experience memory issues, try adding --low_memory at the end of the command: ./run.sh ../img/ ../out/ ../default_params.json 0,1 --low_memory > output.txt

This will free up the memory as much as possible sacrificing the execution speed.

Ensure you have a compatible NVIDIA GPU and CUDA installed. The required shared libraries are included in the libs/ directory.

NOTE: the current CLI version is compiled with CUDA 12.6 and doesn’t always run on different versions. Please consider either updating to CUDA 12.6 following the instructions on this page or using the docker as described below:

Here is the docker image (Ubuntu 22.04, CUDA Runtime 12.6): link

To run it, do the following:

1. Install docker for your system (linux runs natively, for Mac use some container runtime like colima)
2. Install nvidia docker extension (link)
3. Pull the image and run it.
   • docker pull mtsysin/simcli:latest
   • docker run --rm -it --gpus all mtsysin/simcli:latest bash

   If you want to mount additional files, use something like this:

• docker run --rm -it --gpus all -v /home/user/data:/app/data mtsysin/simcli:latest bash

1. Move into the main directory:
   • cd SimCLI/

Now you can run the simulator using the command run.sh as described above.

---

Please send your feedback and bug reports to Misha Tsysin: mtsysin@purdue.edu