Graph::Layout::Aesthetic::Force is a base class for the aesthetic forces used by the Graph::Layout::Aesthetic package. Each force represents one aspect the graph should be optimized for, concepts like "Nodes should be not too close together" or "edges should not be too long". This works by passing the current configuration to the aesth_gradient function in the force module, which then returns a "force" for each node corresponding to how much it would like to move that node in that direction to improve the target aesthetic.

The combination of all forces will then determine the direction and size of the step that's applied to all nodes. The step sizes get restricted by a scalar that's called the "temperature". Since initial step sizes can be big, they don't necessarily improve on the target aesthetics since a step can reach far beyond the minimum for an aesthetic in the given direction (this is intentional so that a state will be able to escape from a local minimum). But as the temperature lowers and the steps get smaller, the steps will more and more tend to optimize the target aesthetic.

This is mainly meant for DAGs (Directed Acyclic Graphs). If a node gets placed to the left of it's parent (position on the first coordinate, the x-axis) plus 5, it wants to move to the other side with a force d**2.

This is again mainly meant for DAGs (Directed Acyclic Graphs). Each node gets assigned a level (its distance from the leafs). Then it tries to give all nodes with the same level at the same distance from the left (position on the first coordinate, the x-axis). The force is d**3 (d is how much the node is to the left or the right from the average position of all nodes of its own level).

The main role of this module is to function as base class for particular forces that are written as XS extension modules. It has a default DESTROY method that frees an assumed underlying C structure, so don't use this as a baseclass for pure perl modules. However, see Graph::Layout::Aesthetic::Force::Perl for how to write forces in perl. On the other hand, if you want to write your own standalone force packages based on XS code, then you'll need to look at Graph::Layout::Aesthetic::Include to get the right definitions of the C level datastructures.

A typical derived class should normally have a module file that loads the XS object and creates one standard instance of the force which it then registers with Graph::Layout::Aesthetic::Force.

The XS object should have a constructor that encapsulates a struct aglo_force (see include/aglo.h) with 3 callback function pointers:

The actual workhorse of the aesthetic force. It will be passed the current state, the pointer returned by aesth_setup and a gradient pointer which is to be filled in with the aesthetic force. The gradient pointer is already initialized with zeros.

The Graph::Layout::Aesthetic::Force module holds a mapping from names to forces. This method registers such a force. The name will be $name, unless that is undefined or not given, in which case it is determined by calling the name method on the given $force. The force corresponding to a given name can be looked up using name2force after this call. A given name can only be registered once.

This looks up $name in the name to force mapping of this module. If found, it directly returns the corresponding force. If not, it tries to require Graph::Layout::Aesthetic::Force::$name and tries again. If still not found, it throws an exception.

Every force object is associated with one scalar of private data (default undef). This is perl data meant for the implementer of a force class, and should normally not be manipulated by the user (see user_data for that).

This method returns that private data.

Don't confuse this with the closure data returned by aesth_setup. That one is associated with a force/state combination and normally only exists as long as a certain force is associated with a certain state, while this one is associated with the force itself.

Every force object is associated with one scalar of user data (default undef). This is perl data meant for the enduser of a force class, and should normally not be manipulated inside the force class (see private_data for that).

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available.