Detailed Description

template<typename NodeIndexType = int32, typename ArcIndexType = int32>
class util::StaticGraph< NodeIndexType, ArcIndexType >

Most efficient implementation of a graph without reverse arcs:

Build() needs to be called after the arc and node have been added.
The graph is really compact memory wise: ArcIndexType * node_capacity() + 2 * NodeIndexType * arc_capacity(), but when Build() is called it uses a temporary extra space of ArcIndexType * arc_capacity().
The construction is really fast.

NOTE(user): if the need arises for very-well compressed graphs, we could shave NodeIndexType * arc_capacity() off the permanent memory requirement with a similar class that doesn't support Tail(), i.e. StaticGraphWithoutTail<>. This almost corresponds to a past implementation of StaticGraph<> @CL 116144340.

Definition at line 396 of file graph.h.

Classes
class	OutgoingArcIterator

Public Types
typedef NodeIndexType	NodeIndex
	Typedef so you can use Graph::NodeIndex and Graph::ArcIndex to be generic but also to improve the readability of your code. More...

typedef ArcIndexType	ArcIndex

Public Member Functions
	StaticGraph ()

	StaticGraph (NodeIndexType num_nodes, ArcIndexType arc_capacity)

NodeIndexType	Head (ArcIndexType arc) const

NodeIndexType	Tail (ArcIndexType arc) const

ArcIndexType	OutDegree (NodeIndexType node) const

BeginEndWrapper< OutgoingArcIterator >	OutgoingArcs (NodeIndexType node) const

BeginEndWrapper< OutgoingArcIterator >	OutgoingArcsStartingFrom (NodeIndexType node, ArcIndexType from) const

BeginEndWrapper< NodeIndexType const * >	operator[] (NodeIndexType node) const
	This loops over the heads of the OutgoingArcs(node). More...

void	ReserveNodes (NodeIndexType bound) override
	Changes the graph capacities. More...

void	ReserveArcs (ArcIndexType bound) override

void	AddNode (NodeIndexType node)

ArcIndexType	AddArc (NodeIndexType tail, NodeIndexType head)

void	Build ()

void	Build (std::vector< ArcIndexType > *permutation)
	Implementation details: A reader may be surprised that we do many passes into the data where things could be done in one pass. More...

NodeIndexType	num_nodes () const
	Returns the number of valid nodes in the graph. More...

ArcIndexType	num_arcs () const
	Returns the number of valid arcs in the graph. More...

IntegerRange< NodeIndex >	AllNodes () const
	Allows nice range-based for loop: for (const NodeIndex node : graph.AllNodes()) { ... More...

IntegerRange< ArcIndex >	AllForwardArcs () const

bool	IsNodeValid (NodeIndexType node) const
	Returns true if the given node is a valid node of the graph. More...

bool	IsArcValid (ArcIndexType arc) const
	Returns true if the given arc is a valid arc of the graph. More...

NodeIndexType	node_capacity () const
	Capacity reserved for future nodes, always >= num_nodes_. More...

ArcIndexType	arc_capacity () const
	Capacity reserved for future arcs, always >= num_arcs_. More...

void	Reserve (NodeIndexType node_capacity, ArcIndexType arc_capacity)

void	FreezeCapacities ()
	FreezeCapacities() makes any future attempt to change the graph capacities crash in DEBUG mode. More...

void	GroupForwardArcsByFunctor (const A &a, B *b)

ArcIndexType	max_end_arc_index () const

Static Public Attributes
static const NodeIndexType	kNilNode
	Constants that will never be a valid node or arc. More...

static const ArcIndexType	kNilArc

Protected Member Functions
void	ComputeCumulativeSum (std::vector< ArcIndexType > *v)
	Functions commented when defined because they are implementation details. More...

void	BuildStartAndForwardHead (SVector< NodeIndexType > head, std::vector< ArcIndexType > start, std::vector< ArcIndexType > *permutation)
	Given the tail of arc #i in (head)[i] and the head of arc #i in (head)[~i]. More...

Protected Attributes
NodeIndexType	num_nodes_

NodeIndexType	node_capacity_

ArcIndexType	num_arcs_

ArcIndexType	arc_capacity_

bool	const_capacities_

Member Typedef Documentation

◆ ArcIndex

typedef ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::ArcIndex

inherited

Definition at line 190 of file graph.h.

◆ NodeIndex

typedef NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::NodeIndex

inherited

Typedef so you can use Graph::NodeIndex and Graph::ArcIndex to be generic but also to improve the readability of your code.

We also recommend that you define a typedef ... Graph; for readability.

Definition at line 189 of file graph.h.

Constructor & Destructor Documentation

◆ StaticGraph() [1/2]

template<typename NodeIndexType = int32, typename ArcIndexType = int32>

util::StaticGraph< NodeIndexType, ArcIndexType >::StaticGraph ( )

inline

Definition at line 406 of file graph.h.

◆ StaticGraph() [2/2]

template<typename NodeIndexType = int32, typename ArcIndexType = int32>

util::StaticGraph< NodeIndexType, ArcIndexType >::StaticGraph	(	NodeIndexType	num_nodes,
		ArcIndexType	arc_capacity
	)

inline

Definition at line 407 of file graph.h.

Member Function Documentation

◆ AddArc()

template<typename NodeIndexType , typename ArcIndexType >

ArcIndexType util::StaticGraph< NodeIndexType, ArcIndexType >::AddArc	(	NodeIndexType	tail,
		NodeIndexType	head
	)

Definition at line 1283 of file graph.h.

◆ AddNode()

template<typename NodeIndexType , typename ArcIndexType >

void util::StaticGraph< NodeIndexType, ArcIndexType >::AddNode ( NodeIndexType node )

Definition at line 1275 of file graph.h.

◆ AllForwardArcs()

IntegerRange< ArcIndexType > util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::AllForwardArcs ( ) const

inherited

Definition at line 935 of file graph.h.

◆ AllNodes()

IntegerRange< NodeIndexType > util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::AllNodes ( ) const

inherited

Allows nice range-based for loop: for (const NodeIndex node : graph.AllNodes()) { ...

BaseGraph implementation -------------------------------------------------—.

} for (const ArcIndex arc : graph.AllForwardArcs()) { ... }

Definition at line 929 of file graph.h.

◆ arc_capacity()

ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::arc_capacity ( ) const

inherited

Capacity reserved for future arcs, always >= num_arcs_.

Todo:: (user): Same questions as the ones in node_capacity().

Definition at line 959 of file graph.h.

◆ Build() [1/2]

template<typename NodeIndexType = int32, typename ArcIndexType = int32>

void util::StaticGraph< NodeIndexType, ArcIndexType >::Build ( )

inline

Definition at line 434 of file graph.h.

◆ Build() [2/2]

template<typename NodeIndexType , typename ArcIndexType >

void util::StaticGraph< NodeIndexType, ArcIndexType >::Build ( std::vector< ArcIndexType > * permutation )

Implementation details: A reader may be surprised that we do many passes into the data where things could be done in one pass.

For instance, during construction, we store the edges first, and then do a second pass at the end to compute the degree distribution.

This is because it is a lot more efficient cache-wise to do it this way. This was determined by various experiments, but can also be understood:

during repetitive call to AddArc() a client usually accesses various areas of memory, and there is no reason to polute the cache with possibly random access to degree[i].
When the degrees are needed, we compute them in one go, maximizing the chance of cache hit during the computation.

If Arc are in order, start_ already contains the degree distribution.

Computes outgoing degree of each nodes. We have to clear start_, since at least the first arc was processed with arc_in_order_ == true.

Computes the forward arc permutation.

Note: this temporarily alters the start_ vector.

We use "tail_" (which now contains rubbish) to permute "head_" faster.

Restore in start_[i] the index of the first arc with tail >= i.

Recompute the correct tail_ vector

Definition at line 1330 of file graph.h.

◆ BuildStartAndForwardHead()

void util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::BuildStartAndForwardHead	(	SVector< NodeIndexType > *	head,
		std::vector< ArcIndexType > *	start,
		std::vector< ArcIndexType > *	permutation
	)

protectedinherited

Given the tail of arc #i in (*head)[i] and the head of arc #i in (*head)[~i].

Reorder the arc by increasing tail.
Put the head of the new arc #i in (*head)[i].
Put in start[i] the index of the first arc with tail >= i.
Update "permutation" to reflect the change, unless it is NULL.

Computes the outgoing degree of each nodes and check if we need to permute something or not. Note that the tails are currently stored in the positive range of the SVector head.

Abort early if we do not need the permutation: we only need to put the heads in the positive range.

Computes the forward arc permutation.

Note: this temporarily alters the start vector.

Restore in (*start)[i] the index of the first arc with tail >= i.

Permutes the head into their final position in head. We do not need the tails anymore at this point.

Definition at line 995 of file graph.h.

◆ ComputeCumulativeSum()

void util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::ComputeCumulativeSum ( std::vector< ArcIndexType > * v )

protectedinherited

Functions commented when defined because they are implementation details.

Computes the cummulative sum of the entry in v.

We only use it with in/out degree distribution, hence the Check() at the end.

Definition at line 978 of file graph.h.

◆ FreezeCapacities()

void util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::FreezeCapacities ( )

inherited

FreezeCapacities() makes any future attempt to change the graph capacities crash in DEBUG mode.

Todo:: (user): Only define this in debug mode at the cost of having a lot of ifndef NDEBUG all over the place? remove the function completely ?

Definition at line 966 of file graph.h.

◆ GroupForwardArcsByFunctor()

void util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::GroupForwardArcsByFunctor	(	const A &	a,
		B *	b
	)

inlineinherited

Todo:: (user): remove the public functions below.

They are just here during the transition from the old ebert_graph api to this new graph api.

Definition at line 264 of file graph.h.

◆ Head()

template<typename NodeIndexType , typename ArcIndexType >

NodeIndexType util::StaticGraph< NodeIndexType, ArcIndexType >::Head ( ArcIndexType arc ) const

Definition at line 1311 of file graph.h.

◆ IsArcValid()

bool util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::IsArcValid ( ArcIndexType arc ) const

inlineinherited

Returns true if the given arc is a valid arc of the graph.

Note: the arc validity range changes for graph with reverse arcs.

Definition at line 219 of file graph.h.

◆ IsNodeValid()

bool util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::IsNodeValid ( NodeIndexType node ) const

inlineinherited

Returns true if the given node is a valid node of the graph.

Definition at line 213 of file graph.h.

◆ max_end_arc_index()

ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::max_end_arc_index ( ) const

inlineinherited

Definition at line 267 of file graph.h.

◆ node_capacity()

NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::node_capacity ( ) const

inherited

Capacity reserved for future nodes, always >= num_nodes_.

Todo:: (user): Is it needed? remove completely? return the real capacities at the cost of having a different implementation for each graphs?

Definition at line 951 of file graph.h.

◆ num_arcs()

ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::num_arcs ( ) const

inlineinherited

Returns the number of valid arcs in the graph.

Definition at line 204 of file graph.h.

◆ num_nodes()

NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::num_nodes ( ) const

inlineinherited

Returns the number of valid nodes in the graph.

Definition at line 201 of file graph.h.

◆ operator[]()

template<typename NodeIndexType , typename ArcIndexType >

BeginEndWrapper< NodeIndexType const * > util::StaticGraph< NodeIndexType, ArcIndexType >::operator[] ( NodeIndexType node ) const

This loops over the heads of the OutgoingArcs(node).

It is just a more convenient way to achieve this. Moreover this interface is used by some graph algorithms.

Definition at line 1246 of file graph.h.

◆ OutDegree()

template<typename NodeIndexType , typename ArcIndexType >

ArcIndexType util::StaticGraph< NodeIndexType, ArcIndexType >::OutDegree ( NodeIndexType node ) const

Definition at line 1253 of file graph.h.

◆ OutgoingArcs()

template<typename NodeIndexType = int32, typename ArcIndexType = int32>

BeginEndWrapper<OutgoingArcIterator> util::StaticGraph< NodeIndexType, ArcIndexType >::OutgoingArcs ( NodeIndexType node ) const

◆ OutgoingArcsStartingFrom()

template<typename NodeIndexType = int32, typename ArcIndexType = int32>

BeginEndWrapper<OutgoingArcIterator> util::StaticGraph< NodeIndexType, ArcIndexType >::OutgoingArcsStartingFrom	(	NodeIndexType	node,
		ArcIndexType	from
	)		const

◆ Reserve()

void util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::Reserve	(	NodeIndexType	node_capacity,
		ArcIndexType	arc_capacity
	)

inlineinherited

Definition at line 247 of file graph.h.

◆ ReserveArcs()

template<typename NodeIndexType , typename ArcIndexType >

void util::StaticGraph< NodeIndexType, ArcIndexType >::ReserveArcs ( ArcIndexType bound )

overridevirtual

Reimplemented from util::BaseGraph< NodeIndexType, ArcIndexType, false >.

Definition at line 1267 of file graph.h.

◆ ReserveNodes()

template<typename NodeIndexType , typename ArcIndexType >

void util::StaticGraph< NodeIndexType, ArcIndexType >::ReserveNodes ( NodeIndexType bound )

overridevirtual

Changes the graph capacities.

The functions will fail in debug mode if:

const_capacities_ is true.
A valid node does not fall into the new node range.
A valid arc does not fall into the new arc range. In non-debug mode, const_capacities_ is ignored and nothing will happen if the new capacity value for the arcs or the nodes is too small.

Reimplemented from util::BaseGraph< NodeIndexType, ArcIndexType, false >.

Definition at line 1259 of file graph.h.

◆ Tail()

template<typename NodeIndexType , typename ArcIndexType >

NodeIndexType util::StaticGraph< NodeIndexType, ArcIndexType >::Tail ( ArcIndexType arc ) const

Definition at line 1304 of file graph.h.

Member Data Documentation

◆ arc_capacity_

ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::arc_capacity_

protectedinherited

Definition at line 279 of file graph.h.

◆ const_capacities_

bool util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::const_capacities_

protectedinherited

Definition at line 280 of file graph.h.

◆ kNilArc

const ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::kNilArc

staticinherited

Definition at line 259 of file graph.h.

◆ kNilNode

const NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::kNilNode

staticinherited

Constants that will never be a valid node or arc.

They are the maximum possible node and arc capacity.

Definition at line 258 of file graph.h.

◆ node_capacity_

NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::node_capacity_

protectedinherited

Definition at line 277 of file graph.h.

◆ num_arcs_

ArcIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::num_arcs_

protectedinherited

Definition at line 278 of file graph.h.

◆ num_nodes_

NodeIndexType util::BaseGraph< NodeIndexType, ArcIndexType, HasReverseArcs >::num_nodes_

protectedinherited

Definition at line 276 of file graph.h.

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

graph.h

Detailed Description

template<typename NodeIndexType = int32, typename ArcIndexType = int32> class util::StaticGraph< NodeIndexType, ArcIndexType >

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ ArcIndex

◆ NodeIndex

Constructor & Destructor Documentation

◆ StaticGraph() [1/2]

◆ StaticGraph() [2/2]

Member Function Documentation

◆ AddArc()

◆ AddNode()

◆ AllForwardArcs()

◆ AllNodes()

◆ arc_capacity()

◆ Build() [1/2]

◆ Build() [2/2]

◆ BuildStartAndForwardHead()

◆ ComputeCumulativeSum()

◆ FreezeCapacities()

◆ GroupForwardArcsByFunctor()

◆ Head()

◆ IsArcValid()

◆ IsNodeValid()

◆ max_end_arc_index()

◆ node_capacity()

◆ num_arcs()

◆ num_nodes()

◆ operator[]()

◆ OutDegree()

◆ OutgoingArcs()

◆ OutgoingArcsStartingFrom()

◆ Reserve()

◆ ReserveArcs()

◆ ReserveNodes()

◆ Tail()

Member Data Documentation

◆ arc_capacity_

◆ const_capacities_

◆ kNilArc

◆ kNilNode

◆ node_capacity_

◆ num_arcs_

◆ num_nodes_

template<typename NodeIndexType = int32, typename ArcIndexType = int32>
class util::StaticGraph< NodeIndexType, ArcIndexType >