For experts: additional features of ULEL

Maximum allowed move per iteration (ULEL)

At each iteration, the layout algorithm moves the nodes a relatively small amount. This amount must not be too large; otherwise, the algorithm might not converge. It must not be too small either or the number of necessary iterations and the running time increase.

The maximum amount of movement at each iteration is controlled by a parameter.

To set this parameter:

In CSS

Add to the GraphLayout section:

maxAllowedMovePerIteration: "10.0";

In Java

Use the method:

void setMaxAllowedMovePerIteration(float maxMove)

Typical values for this setting are 1 - 30, but it depends on the value of the PreferredLinksLength parameter. For example, if the setting for the PreferredLinksLength parameter is 1000, then a value of 100 for the MaxAllowedMovePerIteration parameter is still meaningful.

Link length weight (ULEL)

The layout algorithm is based on the computation of attraction and repulsion forces for each of the nodes and the iterative search of an equilibrium configuration. One of these forces is related to the objective of obtaining a link length close to the specified preferred length. The weight of this force, representing the total amount of force, is controlled by a parameter.

To set this parameter:

In CSS

Add to the GraphLayout section:

linkLengthWeight: "2.25" ;

In Java

Use the method:

void setLinkLengthWeight(float weight)

The default value is 1 . Increasing this parameter can help obtain link lengths closer to the specified length, but increasing too much can increase the number of link crossings.

Additional node repulsion weight (ULEL)

An additional repulsion force can be computed between nodes that are not connected by a link. The weight of this force, representing the total amount of force, is controlled by a parameter.

To set this parameter:

In CSS

Add to the GraphLayout section:

additionalNodeRepulsionWeight: "3.5";

In Java

Use the methods:

void setAdditionalNodeRepulsionWeight(float weight)

The default value of this parameter is 0.2f . Increasing (or decreasing) the weight increases (or decreases) the priority that is given to maintaining the nodes at a distance larger than the node distance threshold (see setNodeDistanceThreshold). However, increasing the weight also decreases the ability of the algorithm to reach convergence quickly.

The following figures enable you to compare the same graph laid out with additional repulsion disabled (Additional repulsion disabled, produced with Uniform Length Edges Layout) and then enabled (Additional repulsion enabled, produced with Uniform Length Edges Layout). You can see that the “star” configuration, where many nodes are connected to the same central node, is better displayed when additional repulsion is enabled.

A star
configuration with additional repulsion disabled

Additional repulsion disabled, produced with Uniform Length Edges Layout

A star
configuration laid out more clearly with additional repulsion enabled

Additional repulsion enabled, produced with Uniform Length Edges Layout

Node distance threshold (ULEL)

The additional repulsion force between two nodes not connected by a link is computed only when their distance is smaller than a predefined distance.

To set this distance:

In CSS

Add to the GraphLayout section:

nodeDistanceThreshold: "4.0";

In Java

Use the method:

void setNodeDistanceThreshold(float threshold)

This additional force is computed only if the additional node repulsion weight is set to a value larger than the default value 0 .

It is recommended that this threshold is set to a value smaller than the preferred length of the links.

Fast multilevel mode: maximum percentage of elapsed time for the refinement step (ULEL)

In fast multilevel mode, the algorithm performs a final refinement step. You can set the maximum percentage of the time already elapsed that must be spent on the final refinement step when the layout mode is FAST_MULTILEVEL_MODE. Increasing the value of this parameter can improve the quality of the layout, possibly at the cost of lower speed.

To set this parameter:

In CSS

Add to the GraphLayout section:

maxPercentageOfElapsedTimeForRefinement: "1000";

In Java

Use the method:

void setMaxPercentageOfElapsedTimeForRefinement(float percentage)

This parameter is only used in fast multilevel mode.

Fast multilevel mode: maximum percentage of total time allowed for the refinement step (ULEL)

In fast multilevel mode, the algorithm performs a final refinement step. You can set the maximum percentage of the total time allowed that must be spent on the final refinement step when the layout mode is FAST_MULTILEVEL_MODE. Increasing the value of this parameter can improve the quality of the layout, possibly at the cost of lower speed.

To set this parameter:

In CSS

Add to the GraphLayout section:

maxPercentageOfTotalAllowedTimeForRefinement: "10";

In Java

Use the method:

void setMaxPercentageOfTotalAllowedTimeForRefinement(float percentage)

This parameter is only used in fast multilevel mode.

Fast multilevel mode: maximum repeat for convergence (ULEL)

You can set the maximum number of attempts to reach convergence at each step when the layout mode is FAST_MULTILEVEL_MODE. Increasing the value of this parameter can improve the quality of the layout, possibly at the cost of lower speed.

To set this parameter:

In CSS

Add to the GraphLayout section:

maxRepeatForConvergence: "3";

In Java

Use the method:

void setMaxRepeatForConvergence(int repeat)

This parameter is only used in fast multilevel mode.