#include <BasicRelax_fwd.hpp>

Detailed Description

Redistributes nodes towards more uniform distribution by minimizing potential between nodes.

The engine first finds num_neighbours closest neighbours. Then it translates each point according to the repelling "force" induced by its neighbours, where it also takes into account target potential. The force is determined by summing the gradients of potentials in surrounding nodes, where amplitude is determined based on distance to the closest neighbour and supplied target density function. The algorithm uses also a primitive Simulated Annealing, i.e. the relax movement magnitude is multiplied with an annealing factor that is linearly dropping from initial_heat to final_heat.

The Engine supports two call types: with supplied distribution function relax(func), where it tries to satisfy the user supplied nodal density function. This can be achieved only when there is the total number of domain nodes the same as integral of density function over the domain. If there is too much nodes a volatile relax might occur. If there is not enough nodes the relax might become lazy. The best use of this mode is in combination with fillDistribution Engines, check test for examples.

Without distribution, where nodes always move towards less populated area regardless anything. The relax magnitude is simply determined from annealing factor and distance to the closest node. A simple and stable approach, however, note that this relax always converges towards uniformly distributed nodes.

Usage example:

    DomainDiscretization<Vec2d> domain = sh.discretizeBoundaryWithStep(fill_density({r, 0.0}));
    GeneralFill<Vec2d> fill_engine; fill_engine.seed(1);
 
    BasicRelax relax_engine;
    relax_engine.iterations(50).initialHeat(1).finalHeat(0.05).boundaryProjectionThreshold(0.75)
            .projectionType(BasicRelax::PROJECT_IN_DIRECTION).numNeighbours(5);
 
    domain.fill(fill_engine, fill_density);
    domain.relax(relax_engine, fill_density);

Definition at line 43 of file BasicRelax_fwd.hpp.

Collaboration diagram for mm::BasicRelax:

Public Member Functions
BasicRelax &	onlyNodes (Range< int > nodes)
	Move only given nodes. More...

BasicRelax &	initialHeat (double in)
	Sets initial heat. More...

BasicRelax &	finalHeat (double in)
	Sets final heat. More...

BasicRelax &	numNeighbours (int neighbours)
	Sets num neighbours. More...

BasicRelax &	potentialOrder (int order)
	Sets order of repulsing potential. More...

BasicRelax &	iterations (int iterations)
	Sets number of iterations. More...

BasicRelax &	rebuildTreeAfter (int iterations)
	Sets rebuild tree frequency. More...

BasicRelax &	projectionType (ProjectionType in)
	Determines how to handle nodes that escape during relaxation. More...

BasicRelax &	boundaryProjectionThreshold (double in)
	Sets threshold for adding nodes on boundary, i.e. if node \(d_1\) and \(d_2\) are distances to closest boundary nodes, do not add node on boundary if \(d_1/d_2 < boundary_projection_threshold \). More...

template<class domain_t >
void	operator() (domain_t &domain) const
	Runs the relax on the selected domain with constant distribution equals to domain characteristic distance. More...

template<class domain_t >
void	operator() (domain_t &domain, double r) const
	Runs the relax on the selected domain with constant density. More...

template<class domain_t , class radius_func_type >
void	operator() (domain_t &domain, const radius_func_type &r_func) const
	Runs the procedure of a given domain. More...

Public Types
enum	ProjectionType { DO_NOT_PROJECT, PROJECT_IN_DIRECTION, PROJECT_BETWEEN_CLOSEST }
	Indicating type of projection used when a relax node goes out of the domain. More...

Private Attributes
int	num_neighbours = 1
	Number of nodes to consider when calculating the potential. More...

int	num_iterations = 50
	Number of iterations performed. More...

double	initial_heat = 1
	Initial heat, usually between 0 and 5. More...

double	final_heat = 0
	Heat at the end of the relax, usually around 0. More...

int	potential_order = 2
	Order of repulsing potential. More...

int	rebuild_tree_after = 1
	How often engine rebuild search tree, 1 is perfect but slow. More...

Range< int >	nodes_
	List of nodes to process. More...

ProjectionType	projection_type = DO_NOT_PROJECT
	On boundary projection method. More...

double	boundary_projection_threshold = 0.75
	Threshold for projecting nodes on boundary. More...

Member Enumeration Documentation

◆ ProjectionType

enum mm::BasicRelax::ProjectionType

Indicating type of projection used when a relax node goes out of the domain.

Enumerator

DO_NOT_PROJECT

Escaped nodes are frozen outside the domain till the end of relax and then removed.

This is good option for violent and unstable relaxations.

PROJECT_IN_DIRECTION

Project on boundary in relax movement direction.

In general produces better distribution on boundaries, but the approximated normals can be bad.

PROJECT_BETWEEN_CLOSEST

Project between two closest boundary nodes – this one might result in divergent behaviour, when both closest nodes are on one side, leading in huge gaps on the boundary.

However, when there are enough boundary nodes in the first place, this works very well.

Definition at line 46 of file BasicRelax_fwd.hpp.

Member Function Documentation

◆ boundaryProjectionThreshold()

BasicRelax & mm::BasicRelax::boundaryProjectionThreshold ( double in )

Sets threshold for adding nodes on boundary, i.e. if node \(d_1\) and \(d_2\) are distances to closest boundary nodes, do not add node on boundary if \(d_1/d_2 < boundary_projection_threshold \).

If threshold is 0 all nodes are added, if it is greater than 1 no nodes are added.

Definition at line 26 of file BasicRelax.cpp.

◆ finalHeat()

BasicRelax & mm::BasicRelax::finalHeat ( double in )

Sets final heat.

Definition at line 18 of file BasicRelax.cpp.

◆ initialHeat()

BasicRelax & mm::BasicRelax::initialHeat ( double in )

Sets initial heat.

Parameters

in	Initial heat, usually between 0 and 5, higher heat means more volatile movement. High initial heat may cause divergence and erratic behaviour. Setting too small initial heat might results in lazy relaxation.

Definition at line 14 of file BasicRelax.cpp.

◆ iterations()

BasicRelax & mm::BasicRelax::iterations ( int iterations )

Sets number of iterations.

Definition at line 37 of file BasicRelax.cpp.

◆ numNeighbours()

BasicRelax & mm::BasicRelax::numNeighbours ( int neighbours )

Sets num neighbours.

Definition at line 33 of file BasicRelax.cpp.

◆ onlyNodes()

BasicRelax & mm::BasicRelax::onlyNodes ( Range< int > nodes )

Move only given nodes.

Definition at line 10 of file BasicRelax.cpp.

◆ operator()() [1/3]

template<class domain_t >

void mm::BasicRelax::operator() ( domain_t & domain ) const

inline

Runs the relax on the selected domain with constant distribution equals to domain characteristic distance.

Parameters

domain domain to process

Definition at line 127 of file BasicRelax_fwd.hpp.

◆ operator()() [2/3]

template<class domain_t , class radius_func_type >

void mm::BasicRelax::operator()	(	domain_t &	domain,
		const radius_func_type &	r_func
	)		const

Runs the procedure of a given domain.

Definition at line 19 of file BasicRelax.hpp.

◆ operator()() [3/3]

template<class domain_t >

void mm::BasicRelax::operator()	(	domain_t &	domain,
		double	r
	)		const

inline

Runs the relax on the selected domain with constant density.

Parameters

domain	domain to process
r	constant density

Definition at line 138 of file BasicRelax_fwd.hpp.

◆ potentialOrder()

BasicRelax & mm::BasicRelax::potentialOrder ( int order )

Sets order of repulsing potential.

Definition at line 41 of file BasicRelax.cpp.

◆ projectionType()

BasicRelax & mm::BasicRelax::projectionType ( ProjectionType in )

Determines how to handle nodes that escape during relaxation.

Definition at line 22 of file BasicRelax.cpp.

◆ rebuildTreeAfter()

BasicRelax & mm::BasicRelax::rebuildTreeAfter ( int iterations )

Sets rebuild tree frequency.

Ir rebuild's tree every in iterations. in = 1 is perfect but slow. Using higher values results in better performance at the cost of accuracy.

Definition at line 45 of file BasicRelax.cpp.

Member Data Documentation

◆ boundary_projection_threshold

double mm::BasicRelax::boundary_projection_threshold = 0.75

private

Threshold for projecting nodes on boundary.

Definition at line 75 of file BasicRelax_fwd.hpp.

◆ final_heat

double mm::BasicRelax::final_heat = 0

private

Heat at the end of the relax, usually around 0.

Definition at line 70 of file BasicRelax_fwd.hpp.

◆ initial_heat

double mm::BasicRelax::initial_heat = 1

private

Initial heat, usually between 0 and 5.

Definition at line 69 of file BasicRelax_fwd.hpp.

◆ nodes_

Range<int> mm::BasicRelax::nodes_

private

List of nodes to process.

Definition at line 73 of file BasicRelax_fwd.hpp.

◆ num_iterations

int mm::BasicRelax::num_iterations = 50

private

Number of iterations performed.

Definition at line 68 of file BasicRelax_fwd.hpp.

◆ num_neighbours

int mm::BasicRelax::num_neighbours = 1

private

Number of nodes to consider when calculating the potential.

Definition at line 67 of file BasicRelax_fwd.hpp.

◆ potential_order

int mm::BasicRelax::potential_order = 2

private

Order of repulsing potential.

Definition at line 71 of file BasicRelax_fwd.hpp.

◆ projection_type

ProjectionType mm::BasicRelax::projection_type = DO_NOT_PROJECT

private

On boundary projection method.

Definition at line 74 of file BasicRelax_fwd.hpp.

◆ rebuild_tree_after

int mm::BasicRelax::rebuild_tree_after = 1

private

How often engine rebuild search tree, 1 is perfect but slow.

Definition at line 72 of file BasicRelax_fwd.hpp.

The documentation for this class was generated from the following files:

include/medusa/bits/domains/BasicRelax_fwd.hpp
include/medusa/bits/domains/BasicRelax.hpp
src/domains/BasicRelax.cpp

Detailed Description

Public Member Functions

Public Types

Private Attributes

Member Enumeration Documentation

◆ ProjectionType

Member Function Documentation

◆ boundaryProjectionThreshold()

◆ finalHeat()

◆ initialHeat()

◆ iterations()

◆ numNeighbours()

◆ onlyNodes()

◆ operator()() [1/3]

◆ operator()() [2/3]

◆ operator()() [3/3]

◆ potentialOrder()

◆ projectionType()

◆ rebuildTreeAfter()

Member Data Documentation

◆ boundary_projection_threshold

◆ final_heat

◆ initial_heat

◆ nodes_

◆ num_iterations

◆ num_neighbours

◆ potential_order

◆ projection_type

◆ rebuild_tree_after