src.demos package

Submodules

src.demos.all_examples module

author

Shahin (Amir Hossein) Rabbani

contact

shahin.rab@gmail.com

copyright

See License

Quick access to all demos

Example: To print 3D Poisson filters, from __main__ run:

Print 3D Poisson filters
run_demo(which=DemoName.IO_PRINT_FILTERS_3D)

Check out DemoName() for all demos. See each method in src.demos for explanation.

Warning

If calling the demos from other paths than the current module, you might get errors with data paths when loading filter or mask data. Adjust your system path accordingly.

Technicals

  • In all demos try to use odd numbers for the domain size because the data domain needs to be symmetrical for most of the demos to work properly.

  • A rank range of \(6 \cdots 8\) for 3D, and \(1 \cdots 4\) for 2D is usually sufficient regardless of the truncation value.

  • Observe when generating the kernel using com.PoissonSolverType.INVERSE, you should multiply the right hand side \(b\) in \(Ax=b\) by \(-1\). When using com.PoissonSolverType.FORWARD this multiplication is not necessary.

    Note

    If going with UNIFIED kernel instead of STANDARD you need the following sign flip in the RHS data to make it work. This is the only downside of benefiting from a UNIFIED kernel.

    data_domain *= -1. if opts.kernel.kernel_type == com.PoissonKernelType.UNIFIED else 1.

    See demos.reductions2d.demo_compare_standard_and_unified_kernels_unreduced_2d().

class src.demos.all_examples.DemoName(value)

Bases: Enum

An enumeration.

BOUNDARY_MULTI_MODAL_COMPLEX_OBJECT = 6
BOUNDARY_TILED_MIRROR = 5
BOUNDARY_VERSATILE_ERROR_SCENARIOS = 7
CONVERGENCE_ADAPTIVE_TRUNCATION_ANALYSIS = 10
CONVERGENCE_COMPARE_3_METHODS_INFINITE_DOMAIN = 8
CONVERGENCE_COMPARE_3_METHODS_WALL_NEUMANN_BOUNDARY = 9
CONVERGENCE_RESIDUAL_COMPARISON_INFINITE_DOMAIN = 11
DECOMPOSITION_EIGENVALUE_ABSORPTION_TEST_2D = 20
IO_DATABASE_GENERATE_2D = 16
IO_DATABASE_GENERATE_3D = 17
IO_DATABASE_SINGLE_FILTER_2D = 18
IO_DATABASE_SINGLE_FILTER_3D = 19
IO_GENERATE_FILTERS_EXPORT_HLSLI_2D = 14
IO_GENERATE_FILTERS_EXPORT_HLSLI_3D = 15
IO_PRINT_FILTERS_2D = 12
IO_PRINT_FILTERS_3D = 13
REDUCTIONS_2D_COMPARE_UNIFIED_STANDARD_KERNELS = 2
REDUCTIONS_2D_PLOT_KERNEL_MODES_FILTERS_CSV_EXPORT = 1
REDUCTIONS_3D_PLOT_FILTERS_TRUNCATION_BEAUTIFIED = 4
REDUCTIONS_3D_PLOT_KERNEL_MODES_FILTERS_CSV_EXPORT = 3
src.demos.all_examples.run_demo(which)
Parameters

which (DemoName) –

src.demos.boundary module

author

Shahin (Amir Hossein) Rabbani

contact

shahin.rab@gmail.com

copyright

See License

src.demos.boundary.add_subplot_matrix(subplot_matrix, opts_subplots, sub_plots, collision_mask, contour_mask, clean_obj_mask_solution_values, title)
src.demos.boundary.compare_jacobi_poisson_filters_neumann_individual_ranks(opts, collision_mask_fname, individual_ranks, verbose=False)

Break down of the Poisson filters solve with individual rank contributions and their cumulative sum. With wall and complex object Neumann boundary treatment using mirror marching algorithm.

Parameters

  • opts (OptionsGeneral) –

  • collision_mask_fname (str) – collision mask file name. See functions.analytics.generate_collision_mask()

  • individual_ranks (List[int]) – list of ranks to be included. Ranks do not have to be consecutive.

  • verbose (bool) – show logs

Returns

Jacobi solution, Poisso filters solution and its individual rank contributions, absolute and relative errors, SSIM components

src.demos.boundary.compare_jacobi_poisson_filters_neumann_simple(opts, collision_mask_fname, verbose=False)

Run a specific experiment to compare ground truth Jacobi solution and Poisson filters solution with Neumann boundary treatment.

Parameters

  • opts (OptionsGeneral) –

  • collision_mask_fname (str) – collision mask file name. See functions.analytics.generate_collision_mask()

  • verbose (bool) – show logs

Returns

ground truth Jacobi solution, Poisson filters solution, errors, generated domain data, collision and contour masks, SSIM components, safe rank

src.demos.boundary.demo_multi_modal_solve_neumann_complex_object_2d(order=60, rank=4, verbose=True)

Plot the break down of the Poisson filters solve visualizing individual rank contributions and their cumulative sum. With wall and complex object Neumann boundary treatment using mirror marching algorithm.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough).

  • verbose (bool) – show logs

src.demos.boundary.demo_versatile_error_scenarios_neumann_2d(rank=4, verbose=True)

Experimenting with various scenarios with different truncation values and Poisson filters order (target Jacobi iteration).

Warning

Solving with current settings might take a while, be patient!

Parameters

  • rank (int) – how many ranks in decomposition (8 or less is usually enough).

  • verbose (bool) – show logs

src.demos.boundary.demo_wall_neumann_tiled_mirrored_2d(order=15, rank=8)

Enforcing Neumann boundary using data reflection technique. Here the input data is extended by tiled mirrors on both horizontal and vertical axes. Solving with \(n\) iteration Jacobi for the input data with explicit Neumann boundary enforcement must be equivalent to convolving the much larger tiled mirrored data with Poisson filters without an explicit boundary condition enforcement. Boundary condition seeks to achieve zero gradient on the edge of the cell

This only works for Neumann, and is the basis for our mirror marching algorithm (see paper). This method is similar to what spectral methods use for enforcing Neumann boundary condition.

How it works: based on the target iteration we compute how much padding the input data needs so that shrinkage of the extended data due to convolution still gives the same matrix size as performing Jacobi after \(n\) iteration.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough)

src.demos.boundary.run_targeted_experiment(order, rank, truncation_method, truncation_value, opts_general, collision_mask_fname, verbose, show_ssim_diff_instead_of_abs_err)

Run a specific experiment to compare ground truth Jacobi solution and Poisson filters solution with Neumann boundary treatment.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough).

  • truncation_method (TruncationMode) – See TruncationMode()

  • truncation_value (float) – TruncationMode()

  • opts_general (OptionsGeneral) –

  • collision_mask_fname (str) – collision mask file name. See functions.analytics.generate_collision_mask()

  • verbose (bool) – show logs

  • show_ssim_diff_instead_of_abs_err (bool) – use SSIM instead of absolute error for the difference

Returns

ground truth Jacobi, error of Poisson filters solution, collision mask, contour mask

src.demos.convergence module

author

Shahin (Amir Hossein) Rabbani

contact

shahin.rab@gmail.com

copyright

See License

Technicals

  • Adaptive truncation:

    Adaptive truncation is based on the ceiling of filter sizes, i.e. maximum filter size needed for a given rank group given a fixed filter value threshold. We can further optimize this by doing per rank filter truncation per iteration as there might certain ranks whose filters can still have elements below the threshold. In general this is a minor optimization and does not have a very significant effect on the performance, but it can make the implementation more complicated, so we did not use it in our results in the paper.

    See demo_adaptive_truncation_analysis_2d() for adaptive truncation per individual rank as well as Poisson filters memory footprint.

  • When solving the inverse Poisson equation, you can generate Poisson kernels with \(\alpha=1\) then just scale the right hand side \(b\) in \(Ax=b\).

src.demos.convergence.compare_jacobi_poisson_no_bc_2d(opts)

Compare Jacobi solution and its residual in the matrix-form to that of the Poisson kernel convolution for an infinite domain (See demo_3methods_comparison_no_bc_2d() for an explanation of the infinite domain).

The Jacobi convergence curve provides a lower bound on the Poisson filter possible solutions. This means if there is no numerical loss due to filter reductions or truncations, Poisson filters must exactly match the convergence behaviour of Jacobi within machine precision, which will be the best case for numerical quality, and worst case performance-wise.

Any reduction or truncation results in degradation of the convergence behaviour in exchange for performance speed up.

Warning

IMPORTANT!

If going with UNIFIED kernel instead of STANDARD you need the following sign flip in the rhs data to make it work. This is the only downside of benefiting from a UNIFIED kernel.

data_domain *= -1. if opts.kernel.kernel_type == com.PoissonKernelType.UNIFIED else 1.
Parameters

opts (OptionsGeneral) –

Returns

Jacobi solution and residuals, Poisson filter solution and residual, errors and generated data

src.demos.convergence.demo_3methods_comparison_no_bc_2d(order=30, rank=8, use_full_poisson_kernel=True)

Sanity check: compare Jacobi solutions, one from the flattened \(Ax=b\) (A.K.A. vector-form) and one for the matrix-form. Also compare them with the Poisson kernel solution achieved through convolution \(L*X=B\).

This is without Neumann boundary enforcement. This effectively means an infinite domain setup. Infinite domain is achieved by dynamically padding the input data based on the desired Jacobi iteration. In other words, we pad the data with sufficiently large blocks so the effects of the wall boundaries never reach inside the domain, where the original much smaller input data exists.

Note

The Poisson kernel (and subsequently its separable filters) are computed based on the matrix-form, so for an infinite domain without any boundary treatment the solution using the Poisson kernel and the one from the matrix-form of Jacobi must match to the machine precision.

In case of using the full kernel, there is no reduction, so we expect an exact match between Jacobi matrix-form and the Poisson filters solution. You can however experiment using Poisson filters by setting use_full_poisson_kernel=False.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough). Only used when in reduction mode.

  • use_full_poisson_kernel (bool) – if True there is no reduction, full kernel convolution. If False, we are either using the reduced square Poisson kernel, or just using the separable filters. Look inside the code for comments on reduce and use_separable_filters variables.

src.demos.convergence.demo_3methods_comparison_with_wall_neumann_bc_2d(order=20, rank=8)

Sanity check: compare Jacobi solutions, one from the flattened \(Ax=b\) (A.K.A. vector-form) and one for the matrix-form. Also compare them with the Poisson kernel solution achieved through convolution \(L*X=B\).

This is with Neumann boundary enforcement. Only for walls. No complex object.

Note

The solutions to Poisson filters and Jacobi matrix-form are supposed to match, but we should expect slight difference between Jacobi matrix-form and Jacobi vector-form due to the way that they deal with corner domain boundary treatment. The results in the paper are achieved with a GPU implementation, where we use Jacobi matrix-form, so as long as Poisson filters and Jacobi matrix-form match we are good.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough). Only used when in reduction mode.

src.demos.convergence.demo_adaptive_truncation_analysis_2d(order=100, rank=8)

Plot maximum rank needed per target iteration given a desired adaptive truncation value, as well as the Poisson filters memory footprint.

Note

In practice little improvement on convergence is observed by using different ranks for different adaptive truncation values. It is safe to use a sufficiently large rank for all target iterations. This helps avoid complicating the implementation. A rank range of \(6 \cdots 8\) for 3D, and \(1 \cdots 4\) for 2D is usually sufficient regardless of the truncation value.

Note

Note the sub-linear memory footprint of the filters as the target iteration grows.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough). Only used when in reduction mode.

Returns

src.demos.convergence.demo_residual_comparison_jacobi_poisson_filters_infinite_domain(order, rank=8, truncation_value=0.0, use_full_poisson_kernel=True)

Compare Jacobi solution and its residual in the matrix-form to that of the Poisson kernel convolution.

Option to use full Poisson kernel (machine precision error is expected compared to Jacobi), or truncated Poisson filters (use_full_poisson_kernel=False)

This is without boundary enforcement. This effectively means an infinite domain setup. Infinite domain is achieved by dynamically padding the input data based on the desired Jacobi iteration. In other words, we pad the data with sufficiently large blocks so the effects of the wall boundaries never reach inside the domain, where the original much smaller input data exists.

In case of using the full kernel, there is no reduction, so we expect an exact match between Jacobi matrix-form and the Poisson filters solution.

Warning

The residual comparison is only valid for inverse Poisson setup. If you ever decide to use the forward Poisson setup keep in mind that while plotting residuals is not reliable (because of the way we compute residuals in our implementation), the actual solutions to Jacobi and Poisson filters perfectly match, as demonstrated in paper results.

The implementation of the matrix form residual for forward Poisson is future work.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough). Only used when in reduction mode.

  • truncation_value (float) – cut-off threshold to trim the filters, given the truncation method in this demo is set to FIXED_THRESHOLD. A 0 value means no truncation.

  • use_full_poisson_kernel (bool) – if True there is no reduction, full kernel convolution. If False, we are either using the reduced square Poisson kernel, or just using the separable filters. Look inside the code for comments on reduce and use_separable_filters variables.

src.demos.convergence.plot_adaptive_truncation_info(trunc_list, rank_filter_info_list, color_list=None)
Parameters

  • trunc_list (List[float]) –

  • rank_filter_info_list (List[tuple]) –

  • color_list (List[str]) –

src.demos.reductions2d module

author

Shahin (Amir Hossein) Rabbani

contact

shahin.rab@gmail.com

copyright

See License

src.demos.reductions2d.demo_compare_standard_and_unified_kernels_unreduced_2d(order=50)

Visually inspecting the differences and similarities between two ways of kernel generation, namely Standard and Unified. Both are full kernels (unreduced) of the same order (same target iteration).

For more info see helper.common.PoissonKernelType().

Note

Observe how the two kernels are the inverse of each other when solver_type = com.PoissonSolverType.INVERSE, while they are the same for FORWARD. When solving the inverse Poisson equation, you should multiply the right hand side \(b\) in \(Ax=b\) by \(-1\).

Parameters

order (int) – filter order (target iteration)

src.demos.reductions2d.plot_and_csv_export_truncated_filters_and_modes_2d(order=50, rank=8, export_csv=True, filter_trim_zeros=True)

Compute the full Poisson kernel, reduce it based on a desired rank, and plot the full kernel, the reduced one, the modes and separable filters.

Option to export as csv. CSV export is useful, for instance, to load and plot filters in Mathematica.

Note

Filter and mode csv files can be found in data/preprocess/components/.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough)

  • export_csv (bool) – exporting the modes and filters as .csv

  • filter_trim_zeros (bool) – True if you want to trim the already zeroed-out elements due to adaptive truncation

src.demos.reductions2d.plot_modes_filters_2d(opts_plots, all_modes, all_filters, safe_rank, specs_info)
Parameters

  • opts_plots (OptionsPlots) –

  • all_modes (List[ndarray]) –

  • all_filters (List[ndarray]) –

  • safe_rank (int) –

  • specs_info (str) –

src.demos.reductions3d module

author

Shahin (Amir Hossein) Rabbani

contact

shahin.rab@gmail.com

copyright

See License

src.demos.reductions3d.demo_plot_filters_adaptive_truncation_beautified_3d(order=60, rank=8, filter_gen_method='load', use_custom_style=True, visualize_truncation=True)

Plot beautified filters with added visuals for the truncated areas. This works only for com.TruncationMode.FIXED_THRESHOLD (adaptive truncation).

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough)

  • filter_gen_method (str) – 'load' or 'generate'. A valid database containing the filters must already exist in data/preprocess/filters/ if choosing to load; else generate them fresh.

  • use_custom_style (bool) – allows for custom background

  • visualize_truncation (bool) – draw the threshold

src.demos.reductions3d.plot_and_csv_export_truncated_filters_and_modes_3d(order, rank, export_csv, filter_trim_zeros)

Generates and plots the Poisson filters for the 3D case, for a given rank and truncation method/value.

Option to export as csv. CSV export is useful, for instance, to load and plot filters in Mathematica.

Note

Filter and mode csv files can be found in data/preprocess/components/.

Parameters

  • order (int) – filter order (target iteration)

  • rank (int) – how many ranks in decomposition (8 or less is usually enough)

  • export_csv (int) – exporting the modes and filters as .csv.

  • filter_trim_zeros (bool) – True if you want to trim the already zeroed-out elements due to adaptive truncation

src.demos.reductions3d.quick_process_filters_3d(single_itr_num, safe_rank, filter_trim_zeros, filter_gen_method, opts, preserve_shape=True)
Parameters

  • single_itr_num (int) – target iteration

  • safe_rank (int) – how many ranks in decomposition (8 or less is usually enough)

  • filter_trim_zeros (bool) – True if you want to trim the already zeroed-out elements due to adaptive truncation

  • filter_gen_method (str) – 'load' or 'generate'

  • opts (OptionsGeneral) –

  • preserve_shape (bool) – if True keep the original shape and fill them with zeros, else return the shrunk filter (Default= True)

Returns

processed filters and filter titles