Getting Started

Package Requirements

Check requirements.txt for packages requirements and their recommended versions.

Run Demos

There are a number of demos available in src.demos.all_examples.py that you should be able to run by selecting a predefined enumerated field in src.demos.all_examples.DemoName() and using it run_demo() in __main__.

Examples

Example 1: print 3D Poisson filters:

run_demo(which=DemoName.IO_PRINT_FILTERS_3D)

You should see:

Console output

Dimension D3
loading database...
Attempting to load filter database ../../data/preprocess/filters/poisson_D3_INVERSE_UNIFIED_dx_1.0_itr_min_1_max_100.npz
done.
//=======Rank 1 ====== [size 99, nonzeros 99 (100.0 %)]  1.38e-39, 1.41e-37, 1.23e-35, 6.25e-34, 2.78e-32, 8.92e-31, 2.60e-29, 5.99e-28, 1.28e-26, 2.25e-25, 3.72e-24, 5.24e-23, 6.97e-22, 8.08e-21, 8.87e-20, 8.63e-19, 7.97e-18, 6.60e-17, 5.20e-16, 3.71e-15, 2.52e-14, 1.56e-13, 9.22e-13, 5.01e-12, 2.59e-11, 1.24e-10, 5.63e-10, 2.38e-09, 9.59e-09, 3.60e-08, 1.29e-07, 4.32e-07, 1.38e-06, 4.13e-06, 1.18e-05, 3.18e-05, 8.17e-05, 1.99e-04, 4.61e-04, 1.02e-03, 2.14e-03, 4.31e-03, 8.36e-03, 1.56e-02, 2.81e-02, 4.95e-02, 8.60e-02, 1.50e-01, 2.74e-01, 5.56e-01, 2.74e-01, 1.50e-01, 8.60e-02, 4.95e-02, 2.81e-02, 1.56e-02, 8.36e-03, 4.31e-03, 2.14e-03, 1.02e-03, 4.61e-04, 1.99e-04, 8.17e-05, 3.18e-05, 1.18e-05, 4.13e-06, 1.38e-06, 4.32e-07, 1.29e-07, 3.60e-08, 9.59e-09, 2.38e-09, 5.63e-10, 1.24e-10, 2.59e-11, 5.01e-12, 9.22e-13, 1.56e-13, 2.52e-14, 3.71e-15, 5.20e-16, 6.60e-17, 7.97e-18, 8.63e-19, 8.87e-20, 8.08e-21, 6.97e-22, 5.24e-23, 3.72e-24, 2.25e-25, 1.28e-26, 5.99e-28, 2.60e-29, 8.92e-31, 2.78e-32, 6.25e-34, 1.23e-35, 1.41e-37, 1.38e-39
//=======Rank 2 ====== [size 99, nonzeros 99 (100.0 %)]  -5.42e-40, -1.57e-37, -6.90e-36, -4.55e-34, -7.58e-33, -3.07e-31, 2.57e-31, -1.56e-29, 3.26e-27, 5.32e-26, 1.73e-24, 2.39e-23, 4.48e-22, 5.17e-21, 7.07e-20, 6.88e-19, 7.41e-18, 6.16e-17, 5.43e-16, 3.89e-15, 2.88e-14, 1.80e-13, 1.13e-12, 6.19e-12, 3.38e-11, 1.62e-10, 7.70e-10, 3.27e-09, 1.36e-08, 5.13e-08, 1.88e-07, 6.32e-07, 2.05e-06, 6.15e-06, 1.78e-05, 4.77e-05, 1.23e-04, 2.96e-04, 6.82e-04, 1.48e-03, 3.05e-03, 5.94e-03, 1.10e-02, 1.92e-02, 3.15e-02, 4.79e-02, 6.54e-02, 7.27e-02, 4.00e-02, -9.95e-02, 4.00e-02, 7.27e-02, 6.54e-02, 4.79e-02, 3.15e-02, 1.92e-02, 1.10e-02, 5.94e-03, 3.05e-03, 1.48e-03, 6.82e-04, 2.96e-04, 1.23e-04, 4.77e-05, 1.78e-05, 6.15e-06, 2.05e-06, 6.32e-07, 1.88e-07, 5.13e-08, 1.36e-08, 3.27e-09, 7.70e-10, 1.62e-10, 3.38e-11, 6.19e-12, 1.13e-12, 1.80e-13, 2.88e-14, 3.89e-15, 5.43e-16, 6.16e-17, 7.41e-18, 6.88e-19, 7.07e-20, 5.17e-21, 4.48e-22, 2.39e-23, 1.73e-24, 5.32e-26, 3.26e-27, -1.56e-29, 2.57e-31, -3.07e-31, -7.58e-33, -4.55e-34, -6.90e-36, -1.57e-37, -5.42e-40
//=======Rank 3 ====== [size 99, nonzeros 99 (100.0 %)]  4.33e-39, -1.38e-37, 1.21e-35, -6.01e-34, 8.55e-33, -8.75e-31, -7.26e-31, -5.94e-28, -2.99e-27, -2.24e-25, -1.40e-24, -5.24e-23, -3.36e-22, -8.07e-21, -4.99e-20, -8.60e-19, -5.01e-18, -6.56e-17, -3.54e-16, -3.67e-15, -1.83e-14, -1.54e-13, -7.04e-13, -4.92e-12, -2.06e-11, -1.21e-10, -4.63e-10, -2.32e-09, -8.10e-09, -3.49e-08, -1.11e-07, -4.16e-07, -1.21e-06, -3.96e-06, -1.05e-05, -3.02e-05, -7.33e-05, -1.87e-04, -4.14e-04, -9.42e-04, -1.91e-03, -3.91e-03, -7.30e-03, -1.35e-02, -2.32e-02, -3.87e-02, -5.90e-02, -7.68e-02, -3.21e-02, 4.22e-01, -3.21e-02, -7.68e-02, -5.90e-02, -3.87e-02, -2.32e-02, -1.35e-02, -7.30e-03, -3.91e-03, -1.91e-03, -9.42e-04, -4.14e-04, -1.87e-04, -7.33e-05, -3.02e-05, -1.05e-05, -3.96e-06, -1.21e-06, -4.16e-07, -1.11e-07, -3.49e-08, -8.10e-09, -2.32e-09, -4.63e-10, -1.21e-10, -2.06e-11, -4.92e-12, -7.04e-13, -1.54e-13, -1.83e-14, -3.67e-15, -3.54e-16, -6.56e-17, -5.01e-18, -8.60e-19, -4.99e-20, -8.07e-21, -3.36e-22, -5.24e-23, -1.40e-24, -2.24e-25, -2.99e-27, -5.94e-28, -7.26e-31, -8.75e-31, 8.55e-33, -6.01e-34, 1.21e-35, -1.38e-37, 4.33e-39
//=======Rank 4 ====== [size 99, nonzeros 99 (100.0 %)]  -1.80e-39, -1.14e-37, -9.12e-37, 6.84e-35, 1.30e-32, 5.32e-31, 2.14e-29, 5.53e-28, 1.38e-26, 2.62e-25, 4.78e-24, 7.10e-23, 1.01e-21, 1.22e-20, 1.40e-19, 1.41e-18, 1.35e-17, 1.14e-16, 9.26e-16, 6.75e-15, 4.68e-14, 2.96e-13, 1.78e-12, 9.79e-12, 5.13e-11, 2.48e-10, 1.14e-09, 4.88e-09, 1.98e-08, 7.51e-08, 2.71e-07, 9.12e-07, 2.92e-06, 8.79e-06, 2.52e-05, 6.79e-05, 1.74e-04, 4.22e-04, 9.74e-04, 2.13e-03, 4.44e-03, 8.79e-03, 1.66e-02, 2.99e-02, 5.13e-02, 8.35e-02, 1.27e-01, 1.75e-01, 1.83e-01, -3.74e-02, 1.83e-01, 1.75e-01, 1.27e-01, 8.35e-02, 5.13e-02, 2.99e-02, 1.66e-02, 8.79e-03, 4.44e-03, 2.13e-03, 9.74e-04, 4.22e-04, 1.74e-04, 6.79e-05, 2.52e-05, 8.79e-06, 2.92e-06, 9.12e-07, 2.71e-07, 7.51e-08, 1.98e-08, 4.88e-09, 1.14e-09, 2.48e-10, 5.13e-11, 9.79e-12, 1.78e-12, 2.96e-13, 4.68e-14, 6.75e-15, 9.26e-16, 1.14e-16, 1.35e-17, 1.41e-18, 1.40e-19, 1.22e-20, 1.01e-21, 7.10e-23, 4.78e-24, 2.62e-25, 1.38e-26, 5.53e-28, 2.14e-29, 5.32e-31, 1.30e-32, 6.84e-35, -9.12e-37, -1.14e-37, -1.80e-39
//=======Rank 5 ====== [size 99, nonzeros 99 (100.0 %)]  -1.46e-39, 1.17e-37, -8.66e-36, 1.84e-34, -1.63e-32, 7.15e-32, -1.43e-29, -2.95e-29, -6.86e-27, -3.15e-26, -1.98e-24, -1.09e-23, -3.71e-22, -2.13e-21, -4.73e-20, -2.65e-19, -4.26e-18, -2.27e-17, -2.78e-16, -1.39e-15, -1.35e-14, -6.28e-14, -4.96e-13, -2.12e-12, -1.39e-11, -5.49e-11, -3.03e-10, -1.10e-09, -5.16e-09, -1.71e-08, -6.93e-08, -2.09e-07, -7.38e-07, -2.04e-06, -6.29e-06, -1.59e-05, -4.32e-05, -9.96e-05, -2.40e-04, -5.07e-04, -1.09e-03, -2.12e-03, -4.12e-03, -7.35e-03, -1.30e-02, -2.15e-02, -3.50e-02, -5.52e-02, -9.61e-02, -2.51e-01, -9.61e-02, -5.52e-02, -3.50e-02, -2.15e-02, -1.30e-02, -7.35e-03, -4.12e-03, -2.12e-03, -1.09e-03, -5.07e-04, -2.40e-04, -9.96e-05, -4.32e-05, -1.59e-05, -6.29e-06, -2.04e-06, -7.38e-07, -2.09e-07, -6.93e-08, -1.71e-08, -5.16e-09, -1.10e-09, -3.03e-10, -5.49e-11, -1.39e-11, -2.12e-12, -4.96e-13, -6.28e-14, -1.35e-14, -1.39e-15, -2.78e-16, -2.27e-17, -4.26e-18, -2.65e-19, -4.73e-20, -2.13e-21, -3.71e-22, -1.09e-23, -1.98e-24, -3.15e-26, -6.86e-27, -2.95e-29, -1.43e-29, 7.15e-32, -1.63e-32, 1.84e-34, -8.66e-36, 1.17e-37, -1.46e-39
//=======Rank 6 ====== [size 99, nonzeros 99 (100.0 %)]  1.35e-39, 1.86e-37, 1.25e-36, 3.54e-34, -7.23e-33, 1.24e-31, -1.21e-29, -7.79e-29, -7.63e-27, -7.08e-26, -2.56e-24, -2.35e-23, -5.26e-22, -4.45e-21, -7.13e-20, -5.43e-19, -6.70e-18, -4.57e-17, -4.52e-16, -2.76e-15, -2.25e-14, -1.23e-13, -8.40e-13, -4.11e-12, -2.39e-11, -1.05e-10, -5.27e-10, -2.08e-09, -9.05e-09, -3.21e-08, -1.22e-07, -3.91e-07, -1.31e-06, -3.79e-06, -1.12e-05, -2.93e-05, -7.72e-05, -1.83e-04, -4.30e-04, -9.25e-04, -1.96e-03, -3.83e-03, -7.30e-03, -1.30e-02, -2.22e-02, -3.52e-02, -5.14e-02, -6.05e-02, -2.52e-02, 1.97e-01, -2.52e-02, -6.05e-02, -5.14e-02, -3.52e-02, -2.22e-02, -1.30e-02, -7.30e-03, -3.83e-03, -1.96e-03, -9.25e-04, -4.30e-04, -1.83e-04, -7.72e-05, -2.93e-05, -1.12e-05, -3.79e-06, -1.31e-06, -3.91e-07, -1.22e-07, -3.21e-08, -9.05e-09, -2.08e-09, -5.27e-10, -1.05e-10, -2.39e-11, -4.11e-12, -8.40e-13, -1.23e-13, -2.25e-14, -2.76e-15, -4.52e-16, -4.57e-17, -6.70e-18, -5.43e-19, -7.13e-20, -4.45e-21, -5.26e-22, -2.35e-23, -2.56e-24, -7.08e-26, -7.63e-27, -7.79e-29, -1.21e-29, 1.24e-31, -7.23e-33, 3.54e-34, 1.25e-36, 1.86e-37, 1.35e-39
//=======Rank 7 ====== [size 99, nonzeros 99 (100.0 %)]  2.64e-39, -4.47e-37, 1.42e-35, -2.13e-33, 1.03e-32, -2.66e-30, 3.27e-30, -1.45e-27, 2.02e-27, -4.17e-25, 1.23e-24, -6.75e-23, 3.96e-22, -6.07e-21, 7.40e-20, -2.17e-19, 8.82e-18, 1.39e-17, 7.14e-16, 2.35e-15, 4.10e-14, 1.58e-13, 1.72e-12, 6.80e-12, 5.37e-11, 2.05e-10, 1.27e-09, 4.58e-09, 2.32e-08, 7.74e-08, 3.29e-07, 1.00e-06, 3.65e-06, 1.01e-05, 3.18e-05, 8.03e-05, 2.19e-04, 5.01e-04, 1.20e-03, 2.47e-03, 5.17e-03, 9.51e-03, 1.74e-02, 2.80e-02, 4.32e-02, 5.68e-02, 6.45e-02, 4.65e-02, 7.65e-03, 1.26e-01, 7.65e-03, 4.65e-02, 6.45e-02, 5.68e-02, 4.32e-02, 2.80e-02, 1.74e-02, 9.51e-03, 5.17e-03, 2.47e-03, 1.20e-03, 5.01e-04, 2.19e-04, 8.03e-05, 3.18e-05, 1.01e-05, 3.65e-06, 1.00e-06, 3.29e-07, 7.74e-08, 2.32e-08, 4.58e-09, 1.27e-09, 2.05e-10, 5.37e-11, 6.80e-12, 1.72e-12, 1.58e-13, 4.10e-14, 2.35e-15, 7.14e-16, 1.39e-17, 8.82e-18, -2.17e-19, 7.40e-20, -6.07e-21, 3.96e-22, -6.75e-23, 1.23e-24, -4.17e-25, 2.02e-27, -1.45e-27, 3.27e-30, -2.66e-30, 1.03e-32, -2.13e-33, 1.42e-35, -4.47e-37, 2.64e-39
//=======Rank 8 ====== [size 99, nonzeros 99 (100.0 %)]  -2.88e-39, 1.40e-37, 5.53e-35, 1.05e-33, 1.10e-31, 1.10e-30, 7.77e-29, 3.97e-28, 2.68e-26, 3.08e-26, 5.01e-24, -1.64e-23, 5.03e-22, -5.58e-21, 1.76e-20, -8.68e-19, -1.92e-18, -8.37e-17, -3.18e-16, -5.52e-15, -2.33e-14, -2.61e-13, -1.10e-12, -9.14e-12, -3.67e-11, -2.41e-10, -9.05e-10, -4.88e-09, -1.69e-08, -7.66e-08, -2.44e-07, -9.41e-07, -2.73e-06, -9.12e-06, -2.41e-05, -7.00e-05, -1.68e-04, -4.28e-04, -9.29e-04, -2.08e-03, -4.06e-03, -7.98e-03, -1.38e-02, -2.31e-02, -3.30e-02, -4.09e-02, -2.93e-02, 2.45e-02, 1.38e-01, 5.07e-02, 1.38e-01, 2.45e-02, -2.93e-02, -4.09e-02, -3.30e-02, -2.31e-02, -1.38e-02, -7.98e-03, -4.06e-03, -2.08e-03, -9.29e-04, -4.28e-04, -1.68e-04, -7.00e-05, -2.41e-05, -9.12e-06, -2.73e-06, -9.41e-07, -2.44e-07, -7.66e-08, -1.69e-08, -4.88e-09, -9.05e-10, -2.41e-10, -3.67e-11, -9.14e-12, -1.10e-12, -2.61e-13, -2.33e-14, -5.52e-15, -3.18e-16, -8.37e-17, -1.92e-18, -8.68e-19, 1.76e-20, -5.58e-21, 5.03e-22, -1.64e-23, 5.01e-24, 3.08e-26, 2.68e-26, 3.97e-28, 7.77e-29, 1.10e-30, 1.10e-31, 1.05e-33, 5.53e-35, 1.40e-37, -2.88e-39

Example 2: visualize the 3D Poisson filters with adaptive truncation:

run_demo(which=DemoName.REDUCTIONS_3D_PLOT_FILTERS_TRUNCATION_BEAUTIFIED)

You should see:

Example 3: plot the residuals of a Jacobi solve vs Poisson filters:

run_demo(which=DemoName.CONVERGENCE_RESIDUAL_COMPARISON_INFINITE_DOMAIN)

You should see:

Tip

A number of pre-generated 2D and 3D filters, and their corresponding decomposition components already exist in different file formats in this repo.

Path to files:

filters (c++/hlsli/npy/npz): data/preprocess/filters
csv: data/preprocess/components

You can also generate/update the existing databases. See IO Handler notes.

Useful 3D filter samples:

For Poisson pressure (already available in the project):

A useful database to immediately get started with in simulation: poisson_D3_INVERSE_STANDARD_dx_1.0_itr_min_1_max_100.hlsli
Useful pre-generated single 3D Poisson filters: single_poisson_D3_INVERSE_STANDARD_dx_1.0_itr_60.hlsli single_poisson_D3_INVERSE_STANDARD_dx_1.0_itr_100.hlsli single_poisson_D3_INVERSE_STANDARD_dx_1.0_itr_200.hlsli
If you experience stability issues with the Poisson solution, try lowering \(dx\). Some examples are pre-generated for you with \(dx=0.9\) (note the _dx_0.9 key in the file name): single_poisson_D3_INVERSE_STANDARD_dx_0.9_itr_60.hlsli single_poisson_D3_INVERSE_STANDARD_dx_0.9_itr_100.hlsli single_poisson_D3_INVERSE_STANDARD_dx_0.9_itr_200.hlsli