Class Network<N extends Node>

Object
AbstractCollection<N>
AbstractList<N>
Network<N>
Type Parameters:
N - the node type managed by the network
All Implemented Interfaces:
Iterable<N>, Collection<N>, Iterator<N>, List<N>, SequencedCollection<N>
Direct Known Subclasses:
Network2D, Network3D
public abstract class Network<N extends Node> extends AbstractList<N> implements Iterator<N>
Abstract graphical representation for generic population geometries. A network corresponds to a (possibly ephemeral) collection and configuration of nodes. Implementations are available in 2D and 3D.
Author:
Christoph Hauert
See Also:

  • Field Details

    • status

      protected Network.Status status
      The status of the network layout.

    • nNodes

      protected int nNodes
      The number of nodes in the network. Convenience variable. This must remain in sync with geometry.getSize() and nodes.length.

    • MIN_DISTANCE

      protected static final double MIN_DISTANCE
      Smallest admissible center-to-center distance during layout calculations. This avoids divisions by zero for coincident nodes.
      See Also:

    • MIN_SCALED_DISTANCE

      protected static final double MIN_SCALED_DISTANCE
      Smallest admissible normalized distance used by the long-range repulsion.
      See Also:

    • HARD_CORE_STIFFNESS

      protected static final double HARD_CORE_STIFFNESS
      Stiffness of the hard-core penalty that separates overlapping nodes. The penalty is quadratic in the overlap depth measured in units of the baseline universe size. The value remains moderate because dense graphs may require a small amount of residual overlap.
      See Also:

    • GOLDEN_ANGLE

      protected static final double GOLDEN_ANGLE
      Golden-angle increment used by deterministic phyllotactic seed layouts.

    • UNIT_RADIUS_REFERENCE_SIZE

      private static final double UNIT_RADIUS_REFERENCE_SIZE
      Reference population size for the baseline node radius law.
      See Also:

    • UNIT_RADIUS_AT_REFERENCE

      private static final double UNIT_RADIUS_AT_REFERENCE
      Baseline radius at UNIT_RADIUS_REFERENCE_SIZE. This preserves the former visual scale around medium-sized populations while allowing the size law to become slightly steeper overall.

    • UNIT_RADIUS_EXPONENT

      private static final double UNIT_RADIUS_EXPONENT
      Exponent of the baseline node radius law. The value is moderately steeper than the former inverse-fourth-root scaling so small populations get noticeably larger nodes and very large populations get a bit smaller still while the reference size remains unchanged.
      See Also:

    • nodes

      protected N extends Node[] nodes
      The array with all nodes of this network.

    • geometry

      protected AbstractGeometry geometry
      The structure of the population.

    • timestamp

      protected double timestamp
      The timestamp of the last time the layouting process has completed.

    • accuracy

      protected double accuracy
      The desired accuracy of the layouting process. The layouting process stops if the change in potential energy falls below this threshold.

    • radius

      double radius
      The radius of the network.

    • isRunning

      protected boolean isRunning
      The flag to indicate whether the layouting process is running.

    • prevPotential

      protected double prevPotential
      The potential energy of the previous network layout/configuration.

    • prevAdjust

      protected double prevAdjust
      The best (smallest) adjustment (lowering of the energy state) of previous layouting steps.

    • initialAdjust

      protected double initialAdjust
      The first observed layout adjustment after the current layout started. This provides the reference scale for estimating how close the current state is to a fully relaxed configuration.

    • layoutProgress

      protected double layoutProgress
      Estimate of how close the current state is to a relaxed layout. Values range from 0 for the initial configuration to 1 once the desired accuracy is reached.

    • norm

      protected double norm
      The normalization factor for the network potential.

    • potential

      protected double potential
      The potential energy of the current network layout/configuration.

    • listener

      protected Network.LayoutListener listener
      The link to the GUI elements interested in updates about the layouting progress.

    • engine

      protected EvoLudo engine
      The pacemaker of all models. Interface with the outside world.

    • rng

      protected RNGDistribution rng
      The random number generator used for layout of networks. Must NOT interfere with modelling and calculations. Do NOT use the shared RNG!
      See Also:

    • layoutTimeout

      protected int layoutTimeout
      The timeout for layout calculations. The default is 5 sec. The layouting process is stopped if it exceeds this time.

    • idx

      private int idx
      Counter for the iterator over all nodes.

  • Constructor Details

    • Network

      protected Network(EvoLudo engine, AbstractGeometry geometry)
      Create a new network for the given engine and geometry.
      Parameters:
      engine - the pacemaker for running the model
      geometry - the structure of the population

  • Method Details

    • setLayoutListener

      public void setLayoutListener(Network.LayoutListener ll)
      Set the layout listener for this network. The layout listener gets notified about the progress of laying out this network.
      Parameters:
      ll - the layout listener

    • reset

      public void reset()
      Reset the network (discard any existing layouts).

    • doLayout

      public abstract void doLayout(Network.LayoutListener nll)
      Start the layouting process. The layout listener (if any) is informed about the progress of the layouting process. Implementations can take advantage of optimizations available for GWT (scheduling) or JRE (multiple threads).
      Parameters:
      nll - the layout listener
      See Also:

    • scaledNodeRadius

      protected double scaledNodeRadius(int nodeidx, double avgTot, double pnorm, double nnorm, double unitradius)
      Compute the radius of a node from its total degree relative to the average degree of the geometry. Positive deviations use pnorm, negative deviations use nnorm.
      Parameters:
      nodeidx - the index of the node
      avgTot - the average total degree of the geometry
      pnorm - the scaling for nodes above the average degree
      nnorm - the scaling for nodes below the average degree
      unitradius - the baseline node radius
      Returns:
      the radius assigned to the node

    • getUnitRadius

      protected double getUnitRadius()
      Compute the baseline node radius used when initializing layouts. The default is anchored at a medium population size and then scales slightly more strongly than inverse-square-root with population size.
      Returns:
      the baseline node radius

    • collectEdges

      protected int collectEdges(int[] sources, int[] targets)
      Collect all unique undirected edges that can be rendered for the current geometry.
      Parameters:
      sources - the array receiving the source node index of each edge
      targets - the array receiving the target node index of each edge
      Returns:
      the number of collected edges

    • collectLinks

      protected int collectLinks(int[] sources, int[] targets, boolean[] isUndirected)
      Collect all renderable links of a directed geometry, collapsing reciprocal pairs into a single undirected edge.
      Parameters:
      sources - the array receiving the source node index of each link
      targets - the array receiving the target node index of each link
      isUndirected - the array receiving whether the collected link is undirected
      Returns:
      the number of collected renderable links

    • sampleIndices

      protected int[] sampleIndices(int itemCount, int sampleCount)
      Draw a random sample without replacement from the integer range [0, itemCount).
      Parameters:
      itemCount - the number of available items
      sampleCount - the number of requested samples
      Returns:
      the sampled indices in randomized order

    • doLayoutPrep

      public void doLayoutPrep()
      Prepare for the layouting process.

    • completeLayout

      protected void completeLayout()
      Finalize the current layout synchronously. This helper is used when a layout is already in its final configuration and therefore does not need any relaxation sweeps before being presented.

    • updateLayoutProgress

      protected double updateLayoutProgress(double adjust)
      Update the estimate of how close the current layout is to a fully relaxed state. The estimate is based on the logarithmic distance between the best adjustment reached so far and the target accuracy relative to the first observed adjustment. A square-root easing spreads out the early part of the curve so progress becomes visible earlier while remaining monotone.
      Parameters:
      adjust - the current change in potential energy after a full relaxation sweep
      Returns:
      the updated progress estimate in [0, 1]

    • getConvergenceAccuracy

      protected double getConvergenceAccuracy()
      Get the effective convergence threshold for the layouting process. The base implementation returns accuracy, but subclasses may tighten or relax the criterion when their layout energies use a different natural scale.
      Returns:
      the effective convergence threshold

    • initNodes

      public abstract void initNodes(double pnorm, double nnorm, double unitradius)
      Generate the initial placement of all nodes. The size of nodes scales with their total number of incoming and outgoing links in heterogeneous networks.
      Parameters:
      pnorm - the maximal radius of a node
      nnorm - the minimal radius of a node
      unitradius - the reference radius of a node

    • relax

      public abstract double relax(int nodeidx)
      Relax the potential energy a single node with index nodeidx by adjusting its position. The potential energy increases proportional to D where D denotes the distance to its neighbours and decreases proportional to 1/D<sup>2</sup> where D refers to the distance from all other nodes.
      Parameters:
      nodeidx - the index of the node to relax
      Returns:
      the change in potential energy

    • relax

      public abstract double relax(int nodeidx, double dt)
      Relaxes the network node with index nodeidx. The attraction and repulsion forces act on the node for a time interval dt, which limits the changes in the position of the node.
      Parameters:
      nodeidx - the index of the node to relax
      dt - the time interval
      Returns:
      the change in potential energy
      See Also:

    • repulsion

      protected abstract double repulsion(int nodeidx)
      Calculate the potential energy based on repulsion for the node with index nodeidx. Return the net repulsion (overall direction and magnitude) acting on it in repulsion(int). Implementations may include additional short-range penalties here, for example to discourage overlap between nodes with finite size.

      Note:

      To prevent disjoint parts of a network (and unstructured populations, in particular) to continue to fly apart, the repulsion changes sign, i.e. turns into attraction, once the distance between nodes exceeds the radius of the universe.
      Parameters:
      nodeidx - the index of the node to relax
      Returns:
      the potential energy of the node

    • attraction

      protected abstract double attraction(int nodeidx)
      Calculate the potential energy based on attraction to its neighbours for the node with index nodeidx. Return the net attraction (overall direction and magnitude) acting on it in attraction(int).
      Parameters:
      nodeidx - the index of the node to relax
      Returns:
      the potential energy of the node

    • finishLayout

      public abstract void finishLayout()
      Add the finishing touches to the graph layout:
      1. shift center of mass into origin
      2. rescale size of graph
      3. find number of links

    • cancelLayout

      public void cancelLayout()
      Abort the layouting process.

    • setLayoutTimout

      public void setLayoutTimout(int msec)
      Set the timeout for layout calculations.
      Parameters:
      msec - the timeout in milliseconds

    • getLayoutTimout

      public int getLayoutTimout()
      Get the timeout for layout calculations.
      Returns:
      the timeout in milliseconds

    • getGeometry

      public AbstractGeometry getGeometry()
      Get the geometry that is backing this network.
      Returns:
      the backing geometry

    • linkNodes

      public abstract void linkNodes()
      Generate the links for the current configuration of the network.

    • shake

      public void shake(Network.LayoutListener ll, double quake)
      Shake the network by randomly shifting the position of all nodes by an amount of up to quake in any coordinate.
      Parameters:
      ll - the layout listener
      quake - the maximum shift in any coordinate

    • scaleRadiusTo

      public void scaleRadiusTo(double newradius)
      Scale the radius of the network to newradius. Scales the radii of all nodes accordingly.
      Parameters:
      newradius - the new radius of the network

    • setRadius

      public void setRadius(double radius)
      Set the radius of the network to radius.
      Parameters:
      radius - the radius of the network

    • getRadius

      public double getRadius()
      Get the radius of the network.
      Returns:
      the radius of the network

    • setStatus

      public void setStatus(Network.Status status)
      Set the status of the layouting process to status.
      Parameters:
      status - the status of the layouting process
      See Also:

    • getStatus

      public Network.Status getStatus()
      Get the status of the layouting process.
      Returns:
      the status of the layouting process

    • isStatus

      public boolean isStatus(Network.Status stat)
      Checks the status of the layouting process.
      Parameters:
      stat - the status to check
      Returns:
      true if the current status is stat

    • getTimestamp

      public double getTimestamp()
      Get the timestamp of the last time the layouting process has completed.
      Returns:
      the timestamp

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<N extends Node>
      Specified by:
      clear in interface List<N extends Node>
      Overrides:
      clear in class AbstractList<N extends Node>

    • size

      public int size()
      Specified by:
      size in interface Collection<N extends Node>
      Specified by:
      size in interface List<N extends Node>
      Specified by:
      size in class AbstractCollection<N extends Node>

    • getNLinks

      public int getNLinks()
      Get the number of links in the network.
      Returns:
      the number of links

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<N extends Node>
      Specified by:
      contains in interface List<N extends Node>
      Overrides:
      contains in class AbstractCollection<N extends Node>

    • set

      public N set(int index, N element)
      Specified by:
      set in interface List<N extends Node>
      Overrides:
      set in class AbstractList<N extends Node>

    • indexOf

      public int indexOf(Object o)
      Specified by:
      indexOf in interface List<N extends Node>
      Overrides:
      indexOf in class AbstractList<N extends Node>

    • lastIndexOf

      public int lastIndexOf(Object o)
      Specified by:
      lastIndexOf in interface List<N extends Node>
      Overrides:
      lastIndexOf in class AbstractList<N extends Node>

    • hasNext

      public boolean hasNext()
      Specified by:
      hasNext in interface Iterator<N extends Node>

    • next

      public N next()
      Specified by:
      next in interface Iterator<N extends Node>

    • iterator

      public Iterator<N> iterator()
      Specified by:
      iterator in interface Collection<N extends Node>
      Specified by:
      iterator in interface Iterable<N extends Node>
      Specified by:
      iterator in interface List<N extends Node>
      Overrides:
      iterator in class AbstractList<N extends Node>

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface Collection<N extends Node>
      Specified by:
      equals in interface List<N extends Node>
      Overrides:
      equals in class AbstractList<N extends Node>

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Collection<N extends Node>
      Specified by:
      hashCode in interface List<N extends Node>
      Overrides:
      hashCode in class AbstractList<N extends Node>