Frameworks¶

Module for the functionality concerning frameworks.

class pyrigi.framework.Framework(graph, realization)[source]¶

Bases: object

This class provides the functionality for frameworks.

Definitions

Parameters:

graph (Graph) – A graph without loops.
realization (dict[Vertex, Point]) – A dictionary mapping the vertices of the graph to points in \(\RR^d\). The dimension \(d\) is retrieved from the points in realization. If graph is empty, and hence also the realization, the dimension is set to 0 (Empty() can be used to construct an empty framework with different dimension).

Examples

>>> F = Framework(Graph([[0,1]]), {0:[1,2], 1:[0,5]})
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1] and edges [[0, 1]]
Realization {0:(1, 2), 1:(0, 5)}

Notice that the realization of a vertex can be accessed using [ ]:

>>> F[0]
Matrix([
[1],
[2]])

Methods

Attribute getters

`dim`	Return the dimension of the framework.
`graph`	Return a copy of the underlying graph.
`realization`([as_points, numerical])	Return a copy of the realization.

Framework properties

`is_congruent`(other_framework[, numerical, ...])	Return whether the given framework is congruent to self.
`is_congruent_realization`(other_realization)	Return whether the given realization is congruent to self.
`is_equivalent`(other_framework[, numerical, ...])	Return whether the given framework is equivalent to self.
`is_equivalent_realization`(other_realization)	Return whether the given realization is equivalent to self.
`is_injective`([numerical, tolerance])	Return whether the realization is injective.
`is_quasi_injective`([numerical, tolerance])	Return whether the realization is quasi-injective.

Class methods

`Circular`(graph)	Return the framework with a regular unit circle realization in the plane.
`Collinear`(graph[, dim])	Return the framework with a realization on the x-axis.
`Complete`(points)	Generate a framework on the complete graph from a given list of points.
`Empty`([dim])	Generate an empty framework.
`Random`(graph[, dim, rand_range])	Return a framework with random realization with integral coordinates.
`Simplicial`(graph[, dim])	Return the framework with a realization on the `dim`-simplex.
`from_points`(points)	Generate a framework from a list of points.

Framework manipulation

`add_edge`(edge)	Add an edge to the framework.
`add_edges`(edges)	Add a list of edges to the framework.
`add_vertex`(point[, vertex])	Add a vertex to the framework with the corresponding coordinates.
`add_vertices`(points[, vertices])	Add a list of vertices to the framework.
`delete_edge`(edge)	Delete an edge from the framework.
`delete_edges`(edges)	Delete a list of edges from the framework.
`delete_vertex`(vertex)	Delete a vertex from the framework.
`delete_vertices`(vertices)	Delete a list of vertices from the framework.
`projected_realization`([proj_dim, ...])	Return the realization projected to a lower dimension and the projection matrix.
`rescale`(factor[, inplace])	Scale the framework.
`rotate2D`(angle[, inplace])	Rotate the planar framework counterclockwise.
`set_realization`(realization)	Change the realization of the framework.
`set_vertex_pos`(vertex, point)	Change the coordinates of a single given vertex.
`set_vertex_positions`(subset_of_realization)	Change the coordinates of vertices given by a dictionary.
`set_vertex_positions_from_lists`(vertices, points)	Change the coordinates of a given list of vertices.
`translate`(vector[, inplace])	Translate the framework.

Infinitesimal rigidity

`inf_flexes`([include_trivial, vertex_order, ...])	Return a basis of the space of infinitesimal flexes.
`is_dependent`()	Return whether the framework is dependent.
`is_dict_inf_flex`(vert_to_flex, **kwargs)	Return whether a dictionary specifies an infinitesimal flex of the framework.
`is_dict_nontrivial_inf_flex`(vert_to_flex, ...)	Return whether a dictionary specifies an infinitesimal flex which is nontrivial.
`is_dict_stress`(dict_stress, **kwargs)	Return whether a dictionary specifies an equilibrium stress of the framework.
`is_dict_trivial_inf_flex`(inf_flex, **kwargs)	Return whether an infinitesimal flex specified by a dictionary is trivial.
`is_independent`()	Return whether the framework is independent.
`is_inf_flexible`()	Return whether the framework is infinitesimally flexible.
`is_inf_rigid`()	Return whether the framework is infinitesimally rigid.
`is_isostatic`()	Return whether the framework is isostatic.
`is_min_inf_rigid`()	Return whether the framework is minimally infinitesimally rigid.
`is_nontrivial_flex`(inf_flex, **kwargs)	Alias for `is_vector_nontrivial_inf_flex()` and `is_dict_nontrivial_inf_flex()`.
`is_redundantly_inf_rigid`()	Return if the framework is infinitesimally redundantly rigid.
`is_stress`(stress, **kwargs)	Alias for `is_vector_stress()` and `is_dict_stress()`.
`is_trivial_flex`(inf_flex, **kwargs)	Alias for `is_vector_trivial_inf_flex()` and `is_dict_trivial_inf_flex()`.
`is_vector_inf_flex`(inf_flex[, vertex_order, ...])	Return whether a vector is an infinitesimal flex of the framework.
`is_vector_nontrivial_inf_flex`(inf_flex[, ...])	Return whether an infinitesimal flex is nontrivial.
`is_vector_stress`(stress[, edge_order, ...])	Return whether a vector is an equilibrium stress.
`is_vector_trivial_inf_flex`(inf_flex, **kwargs)	Return whether an infinitesimal flex is trivial.
`nontrivial_inf_flexes`(**kwargs)	Return non-trivial infinitesimal flexes.
`rigidity_matrix`([vertex_order, edge_order])	Construct the rigidity matrix of the framework.
`rigidity_matrix_rank`()	Return the rank of the rigidity matrix.
`stress_matrix`(stress[, edge_order, vertex_order])	Construct the stress matrix of a stress.
`stresses`([edge_order, numerical, tolerance])	Return a basis of the space of equilibrium stresses.
`trivial_inf_flexes`([vertex_order])	Return a basis of the vector subspace of trivial infinitesimal flexes.

Plotting

`animate3D_rotation`([plot_style, ...])	Plot this framework in 3D and animate a rotation around an axis.
`plot`([plot_style])	Plot the framework.
`plot2D`([plot_style, projection_matrix, ...])	Plot the framework in 2D.
`plot3D`([plot_style, projection_matrix, ...])	Plot the provided framework in 3D.

Other

`edge_lengths`([numerical])	Return the dictionary of the edge lengths.
`generate_stl_bars`([scale, width_of_bars, ...])	Generate STL files for the bars of the framework.
`is_prestress_stable`([numerical, tolerance, ...])	Return whether the framework is prestress stable.
`is_second_order_rigid`([numerical, ...])	Return whether the framework is second-order rigid.
`to_tikz`([vertex_style, edge_style, ...])	Create a TikZ code for the framework.

Notes

Internally, the realization is represented as dict[Vertex,Matrix]. However, realization() can also return dict[Vertex,Point].

classmethod Circular(graph)[source]¶

Return the framework with a regular unit circle realization in the plane.

Parameters:: graph (Graph) – Underlying graph on which the framework is constructed.
Return type:: Framework

Examples

>>> import pyrigi.graphDB as graphs
>>> F = Framework.Circular(graphs.CompleteBipartite(4, 2))
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1, 2, 3, 4, 5] and edges ...
Realization {0:(1, 0), 1:(1/2, sqrt(3)/2), ...

classmethod Collinear(graph, dim=1)[source]¶

Return the framework with a realization on the x-axis.

Parameters:

dim (int) – The dimension of the space in which the framework is constructed.
graph (Graph) – Underlying graph on which the framework is constructed.

Return type:

Framework

Examples

>>> import pyrigi.graphDB as graphs
>>> print(Framework.Collinear(graphs.Complete(3), dim=2))
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1, 2] and edges [[0, 1], [0, 2], [1, 2]]
Realization {0:(0, 0), 1:(1, 0), 2:(2, 0)}

classmethod Complete(points)[source]¶

Generate a framework on the complete graph from a given list of points.

The vertices of the underlying graph are taken to be the list [0,...,len(points)-1].

Parameters:: points (Sequence[Point]) – The realization of the framework that this method outputs is provided as a list of points.
Return type:: Framework

Examples

>>> F = Framework.Complete([(1,),(2,),(3,),(4,)]); print(F)
Framework in 1-dimensional space consisting of:
Graph with vertices [0, 1, 2, 3] and edges [[0, 1], [0, 2], [0, 3], [1, 2], [1, 3], [2, 3]]
Realization {0:(1,), 1:(2,), 2:(3,), 3:(4,)}

classmethod Empty(dim=2)[source]¶

Generate an empty framework.

Parameters:: dim (int) – A natural number that determines the dimension in which the framework is realized.
Return type:: Framework

Examples

>>> F = Framework.Empty(dim=1); print(F)
Framework in 1-dimensional space consisting of:
Graph with vertices [] and edges []
Realization {}

classmethod Random(graph, dim=2, rand_range=None)[source]¶

Return a framework with random realization with integral coordinates.

Parameters:

dim (int) – The dimension of the constructed framework.
graph (Graph) – Graph for which the random realization should be constructed.
rand_range (int | Sequence[int]) – Sets the range of random numbers from which the realization is sampled. The format is either an interval (a,b) or a single integer a, which produces the range (-a,a). If rand_range=None, then the range is set to (-a,a) for a = 10^4 * n * dim, where n is the number of vertices.

Return type:

Framework

Examples

>>> F = Framework.Random(Graph([(0,1), (1,2), (0,2)]))
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1, 2] and edges [[0, 1], [0, 2], [1, 2]]
Realization {0:(122, 57), 1:(27, 144), 2:(50, 98)}

classmethod Simplicial(graph, dim=None)[source]¶

Return the framework with a realization on the dim-simplex.

Parameters:

graph (Graph) – Underlying graph on which the framework is constructed.
dim (int) – The dimension dim has to be at least the number of vertices of the graph minus one. If dim is not specified, then the least possible one is used.

Return type:

Framework

Examples

>>> F = Framework.Simplicial(Graph([(0,1), (1,2), (2,3), (0,3)]), 4)
>>> F.realization(as_points=True)
{0: [0, 0, 0, 0], 1: [1, 0, 0, 0], 2: [0, 1, 0, 0], 3: [0, 0, 1, 0]}
>>> F = Framework.Simplicial(Graph([(0,1), (1,2), (2,3), (0,3)]))
>>> F.realization(as_points=True)
{0: [0, 0, 0], 1: [1, 0, 0], 2: [0, 1, 0], 3: [0, 0, 1]}

__getitem__(vertex)[source]¶

Return the coordinates of a given vertex in the realization.

Parameters:: vertex (Vertex)
Return type:: MutableDenseMatrix

Examples

>>> F = Framework(Graph([[0,1]]), {0:[1,2], 1:[0,5]})
>>> F[0]
Matrix([
[1],
[2]])

__repr__()[source]¶

Return a representation of the framework.

Return type:: str

__str__()[source]¶

Return the string representation.

Return type:: str

add_edge(edge)[source]¶

Add an edge to the framework.

Parameters:: edge (Edge)
Return type:: None

Notes

This method only alters the graph attribute.

add_edges(edges)[source]¶

Add a list of edges to the framework.

Parameters:: edges (Sequence[Edge])
Return type:: None

Notes

For each edge that has to be added, add_edge() is called.

add_vertex(point, vertex=None)[source]¶

Add a vertex to the framework with the corresponding coordinates.

If no vertex is provided (None), then an integer is chosen instead.

Parameters:

point (Point) – The realization of the new vertex.
vertex (Vertex) – The label of the new vertex.

Return type:

None

Examples

>>> F = Framework.Empty(dim=2)
>>> F.add_vertex((1.5,2), 'a')
>>> F.add_vertex((3,1))
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices ['a', 1] and edges []
Realization {a:(1.50000000000000, 2), 1:(3, 1)}

add_vertices(points, vertices=None)[source]¶

Add a list of vertices to the framework.

Parameters:

points (Sequence[Point]) – List of points consisting of coordinates in \(\RR^d\). It is checked that all points lie in the same ambient space.
vertices (Sequence[Vertex]) – List of vertices. If the list of vertices is empty, we generate vertices with the method add_vertex(). Otherwise, the list of vertices needs to have the same length as the list of points.

Return type:

None

Examples

>>> F = Framework.Empty(dim=2)
>>> F.add_vertices([(1.5,2), (3,1)], ['a',0])
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices ['a', 0] and edges []
Realization {a:(1.50000000000000, 2), 0:(3, 1)}

Notes

For each vertex that has to be added, add_vertex() is called.

animate3D_rotation(plot_style=None, edge_colors_custom=None, total_frames=100, delay=75, rotation_axis=None, **kwargs)[source]¶

Plot this framework in 3D and animate a rotation around an axis.

Parameters:

plot_style (PlotStyle) – An instance of the PlotStyle class that defines the visual style for plotting, see PlotStyle for more details.
edge_colors_custom (Sequence[Sequence[Edge]] | dict[str, Sequence[Edge]]) – Optional parameter to specify the colors of edges. It can be a Sequence[Sequence[Edge]] to define groups of edges with the same color or a dict[str, Sequence[Edge]] where the keys are color strings and the values are lists of edges. The ommited edges are given the value plot_style.edge_color.
total_frames (int) – Total number of frames for the animation sequence.
delay (int) – Delay between frames in milliseconds.
rotation_axis (str | Sequence[Number]) – The user can input a rotation axis or vector. By default, a rotation around the z-axis is performed. This can either a character ('x', 'y', or 'z') or a vector (e.g. [1, 0, 0]).

Return type:

Any

Examples

>>> from pyrigi import frameworkDB
>>> F = frameworkDB.Complete(4, dim=3)
>>> F.animate3D_rotation()

delete_edge(edge)[source]¶

Delete an edge from the framework.

Parameters:: edge (Edge)
Return type:: None

delete_edges(edges)[source]¶

Delete a list of edges from the framework.

Parameters:: edges (Sequence[Edge])
Return type:: None

delete_vertex(vertex)[source]¶

Delete a vertex from the framework.

Parameters:: vertex (Vertex)
Return type:: None

delete_vertices(vertices)[source]¶

Delete a list of vertices from the framework.

Parameters:: vertices (Sequence[Vertex])
Return type:: None

property dim: int¶: Return the dimension of the framework.

edge_lengths(numerical=False)[source]¶

Return the dictionary of the edge lengths.

Parameters:: numerical (bool) – If True, numerical positions are used for the computation of the edge lengths.
Return type:: dict[Edge, Number]

Examples

>>> G = Graph([(0,1), (1,2), (2,3), (0,3)])
>>> F = Framework(G, {0:[0,0], 1:[1,0], 2:[1,'1/2 * sqrt(5)'], 3:['1/2','4/3']})
>>> F.edge_lengths(numerical=False)
{(0, 1): 1, (0, 3): sqrt(73)/6, (1, 2): sqrt(5)/2, (2, 3): sqrt((-4/3 + sqrt(5)/2)**2 + 1/4)}
>>> F.edge_lengths(numerical=True)
{(0, 1): 1.0, (0, 3): 1.4240006242195884, (1, 2): 1.118033988749895, (2, 3): 0.5443838790578374}

classmethod from_points(points)[source]¶

Generate a framework from a list of points.

The list of vertices of the underlying graph is taken to be [0,...,len(points)-1]. The underlying graph has no edges.

Parameters:: points (Sequence[Point]) – The realization of the framework that this method outputs is provided as a list of points.
Return type:: Framework

Examples

>>> F = Framework.from_points([(1,2), (2,3)])
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1] and edges []
Realization {0:(1, 2), 1:(2, 3)}

generate_stl_bars(scale=1.0, width_of_bars=8.0, height_of_bars=3.0, holes_diameter=4.3, filename_prefix='bar_', output_dir='stl_output')[source]¶

Generate STL files for the bars of the framework.

The STL files are generated in the working folder. The naming convention for the files is bar_i-j.stl, where i and j are the vertices of an edge.

Parameters:

scale (float) – Scale factor for the lengths of the edges, default is 1.0.
width_of_bars (float) – Width of the bars, default is 8.0 mm.
height_of_bars (float) – Height of the bars, default is 3.0 mm.
holes_diameter (float) – Diameter of the holes at the ends of the bars, default is 4.3 mm.
filename_prefix (str) – Prefix for the filenames of the generated STL files, default is bar_.
output_dir (str) – Name or path of the folder where the STL files are saved, default is stl_output. Relative to the working directory.

Return type:

None

Examples

>>> G = Graph([(0,1), (1,2), (2,3), (0,3)])
>>> F = Framework(G, {0:[0,0], 1:[1,0], 2:[1,'1/2 * sqrt(5)'], 3:[1/2,'4/3']})
>>> F.generate_stl_bars(scale=20)
STL files for the bars have been generated in the folder `stl_output`.

property graph: Graph¶

Return a copy of the underlying graph.

Examples

>>> F = Framework.Random(Graph([(0,1), (1,2), (0,2)]))
>>> print(F.graph)
Graph with vertices [0, 1, 2] and edges [[0, 1], [0, 2], [1, 2]]

inf_flexes(include_trivial=False, vertex_order=None, numerical=False, tolerance=1e-09)[source]¶

Return a basis of the space of infinitesimal flexes.

Return a lift of a basis of the quotient of the vector space of infinitesimal flexes modulo trivial infinitesimal flexes, if include_trivial=False. Return a basis of the vector space of infinitesimal flexes if include_trivial=True.

Definitions

Infinitesimal flex

Parameters:

include_trivial (bool) – Boolean that decides, whether the trivial flexes should be included.
vertex_order (Sequence[Vertex]) – A list of vertices, providing the ordering for the entries of the infinitesimal flexes. If none is provided, the list from Graph.vertex_list() is taken.
numerical (bool) – Determines whether the output is symbolic (default) or numerical.
tolerance (float) – Used tolerance when computing the infinitesimal flex numerically.

Return type:

list[MutableDenseMatrix] | list[list[float]]

Examples

>>> F = Framework.Complete([[0,0], [1,0], [1,1], [0,1]])
>>> F.delete_edges([(0,2), (1,3)])
>>> F.inf_flexes(include_trivial=False)
[Matrix([
[1],
[0],
[1],
[0],
[0],
[0],
[0],
[0]])]
>>> F = Framework(
...     Graph([[0, 1], [0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]),
...     {0: [0, 0], 1: [0, 1], 2: [0, 2], 3: [1, 2], 4: [-1, 2]},
... )
>>> F.inf_flexes()
[Matrix([
[0],
[0],
[0],
[0],
[0],
[1],
[0],
[0],
[0],
[0]])]

is_congruent(other_framework, numerical=False, tolerance=1e-09)[source]¶

Return whether the given framework is congruent to self.

Definitions

Congruent frameworks

Parameters:

other_framework (Framework) – The framework for checking the congruence.
numerical (bool) – Whether the check is symbolic (default) or numerical.
tolerance (float) – Used tolerance when checking numerically.

Return type:

bool

is_congruent_realization(other_realization, numerical=False, tolerance=1e-09)[source]¶

Return whether the given realization is congruent to self.

Definitions

Congruent frameworks

Parameters:

other_realization (dict[Vertex, Point] | dict[Vertex, MutableDenseMatrix]) – The realization for checking the congruence.
numerical (bool) – Whether the check is symbolic (default) or numerical.
tolerance (float) – Used tolerance when checking numerically.

Return type:

bool

is_dependent()[source]¶

Return whether the framework is dependent.

See also is_second_order_rigid().

Definitions

Prestress stability

Parameters:

numerical (bool) – If True, numerical infinitesimal flexes and stresses are used in the check for prestress stability. In case that numerical=False, this method only properly works for symbolic coordinates.
tolerance (float) – Numerical tolerance used for the check that something is an approximate zero.
inf_flexes (Sequence[InfFlex]) – Precomputed infinitesimal flexes and equilibrium stresses can be provided to avoid recomputation. If not provided, they are computed here.
stresses (Sequence[Stress]) – Precomputed infinitesimal flexes and equilibrium stresses can be provided to avoid recomputation. If not provided, they are computed here.

Return type:

bool

Examples

>>> from pyrigi import frameworkDB as fws
>>> F = fws.Frustum(3)
>>> F.is_prestress_stable()
True

is_quasi_injective(numerical=False, tolerance=1e-09)[source]¶

Return whether the realization is quasi-injective.

Definitions

Quasi-injectivity

Parameters:

numerical (bool) – Whether the check is symbolic (default) or numerical.
tolerance (float) – Used tolerance when checking numerically.

Return type:

bool

Notes

For comparing whether two vectors are the same, misc.is_zero_vector() is used. See its documentation for the description of the parameters.

is_redundantly_inf_rigid()[source]¶

Return if the framework is infinitesimally redundantly rigid.

Return type:: bool

Definitions

Redundant infinitesimal rigidity

Examples

>>> F = Framework.Empty(dim=2)
>>> F.add_vertices([(1,0), (1,1), (0,3), (-1,1)], ['a','b','c','d'])
>>> F.add_edges([('a','b'), ('b','c'), ('c','d'), ('a','d'), ('a','c'), ('b','d')])
>>> F.is_redundantly_inf_rigid()
True
>>> F.delete_edge(('a','c'))
>>> F.is_redundantly_inf_rigid()
False

is_second_order_rigid(numerical=False, tolerance=1e-09, inf_flexes=None, stresses=None)[source]¶

Return whether the framework is second-order rigid.

Checking second-order-rigidity for a general framework is computationally hard. If there is only one stress or only one infinitesimal flex, second-order rigidity is identical to prestress stability, so we can apply is_prestress_stable(). See also Theorem 33.

Definitions

Second-order rigidity

Parameters:

numerical (bool) – If True, numerical infinitesimal flexes and stresses are used in the check for prestress stability. In case that numerical=False, this method only properly works for symbolic coordinates.
tolerance (float) – Numerical tolerance used for the check that something is an approximate zero.
inf_flexes (Sequence[InfFlex]) – Precomputed infinitesimal flexes and equilibrium stresses can be provided to avoid recomputation. If not provided, they are computed here.
stresses (Sequence[Stress]) – Precomputed infinitesimal flexes and equilibrium stresses can be provided to avoid recomputation. If not provided, they are computed here.

Return type:

bool

Examples

>>> from pyrigi import frameworkDB as fws
>>> F = fws.Frustum(3)
>>> F.is_second_order_rigid()
True

is_stress(stress, **kwargs)[source]¶

Alias for is_vector_stress() and is_dict_stress().

One of the alias methods is called depending on the type of the input.

Parameters:: stress (Stress)
Return type:: bool

is_trivial_flex(inf_flex, **kwargs)[source]¶

Alias for is_vector_trivial_inf_flex() and is_dict_trivial_inf_flex().

Ii is distinguished between instances of list and instances of dict to call one of the alias methods.

Definitions

Trivial infinitesimal flex

Parameters:: inf_flex (InfFlex)
Return type:: bool

is_vector_inf_flex(inf_flex, vertex_order=None, numerical=False, tolerance=1e-09)[source]¶

Return whether a vector is an infinitesimal flex of the framework.

Definitions

Parameters:

inf_flex (Sequence[Number]) – An infinitesimal flex of the framework specified by a vector.
vertex_order (Sequence[Vertex]) – A list of vertices specifying the order in which inf_flex is given. If none is provided, the list from vertex_list() is taken.
numerical (bool) – A Boolean determining whether the evaluation of the product of the inf_flex and the rigidity matrix is symbolic or numerical.
tolerance (float) – Absolute tolerance that is the threshold for acceptable numerical flexes. This parameter is used to determine the number of digits, to which accuracy the symbolic expressions are evaluated.

Return type:

bool

Examples

>>> from pyrigi import frameworkDB as fws
>>> F = fws.Square()
>>> q = [0,0,0,0,-2,0,-2,0]
>>> F.is_vector_inf_flex(q)
True
>>> q[0] = 1
>>> F.is_vector_inf_flex(q)
False
>>> F = Framework.Complete([[0,0], [1,1]])
>>> F.is_vector_inf_flex(["sqrt(2)","-sqrt(2)",0,0], vertex_order=[1,0])
True

is_vector_nontrivial_inf_flex(inf_flex, vertex_order=None, numerical=False, tolerance=1e-09)[source]¶

Return whether an infinitesimal flex is nontrivial.

Definitions

Nontrivial infinitesimal flex

Parameters:

inf_flex (Sequence[Number]) – An infinitesimal flex of the framework.
vertex_order (Sequence[Vertex]) – A list of vertices specifying the order in which inf_flex is given. If none is provided, the list from Graph.vertex_list() is taken.
numerical (bool) – A Boolean determining whether the evaluation of the product of the inf_flex and the rigidity matrix is symbolic or numerical.
tolerance (float) – Absolute tolerance that is the threshold for acceptable numerical flexes. This parameter is used to determine the number of digits, to which accuracy the symbolic expressions are evaluated.

Return type:

bool

Examples

>>> from pyrigi import frameworkDB as fws
>>> F = fws.Square()
>>> q = [0,0,0,0,-2,0,-2,0]
>>> F.is_vector_nontrivial_inf_flex(q)
True
>>> q = [1,-1,1,1,-1,1,-1,-1]
>>> F.is_vector_inf_flex(q)
True
>>> F.is_vector_nontrivial_inf_flex(q)
False

Notes

This is done by solving a linear system composed of a matrix \(A\) whose columns are given by a basis of the trivial flexes and the vector \(b\) given by the input flex. \(b\) is trivial if and only if there is a linear combination of the columns in \(A\) producing \(b\). In other words, when there is a solution to \(Ax=b\), then \(b\) is a trivial infinitesimal motion. Otherwise, \(b\) is nontrivial.

In the numerical=True case we compute a least squares solution \(x\) of the overdetermined linear system and compare the values in \(Ax\) to the values in \(b\).

is_vector_stress(stress, edge_order=None, numerical=False, tolerance=1e-09)[source]¶

Return whether a vector is an equilibrium stress.

Definitions

Equilibrium stress

Parameters:

stress (Sequence[Number]) – A vector to be checked whether it is a stress of the framework.
edge_order (Sequence[Edge]) – A list of edges, providing the ordering for the entries of the stress. If none is provided, the list from Graph.edge_list() is taken.
numerical (bool) – A Boolean determining whether the evaluation of the product of the stress and the rigidity matrix is symbolic or numerical.
tolerance – Absolute tolerance that is the threshold for acceptable equilibrium stresses. This parameter is used to determine the number of digits, to which accuracy the symbolic expressions are evaluated.

Return type:

bool

Examples

>>> G = Graph([[0,1],[0,2],[0,3],[1,2],[2,3],[3,1]])
>>> pos = {0: (0, 0), 1: (0,1), 2: (-1,-1), 3: (1,-1)}
>>> F = Framework(G, pos)
>>> omega1 = [-8, -4, -4, 2, 2, 1]
>>> F.is_stress(omega1)
True
>>> omega1[0] = 0
>>> F.is_stress(omega1)
False
>>> from pyrigi import frameworkDB
>>> F = frameworkDB.Complete(5, dim=2)
>>> stresses=F.stresses()
>>> F.is_stress(stresses[0])
True

is_vector_trivial_inf_flex(inf_flex, **kwargs)[source]¶

Return whether an infinitesimal flex is trivial.

See also is_nontrivial_vector_inf_flex() for details, particularly concerning the possible parameters.

Definitions

Trivial infinitesimal flex

Parameters:: inf_flex (Sequence[Number]) – An infinitesimal flex of the framework.
Return type:: bool

Examples

>>> from pyrigi import frameworkDB as fws
>>> F = fws.Square()
>>> q = [0,0,0,0,-2,0,-2,0]
>>> F.is_vector_trivial_inf_flex(q)
False
>>> q = [1,-1,1,1,-1,1,-1,-1]
>>> F.is_vector_trivial_inf_flex(q)
True

nontrivial_inf_flexes(**kwargs)[source]¶

Return non-trivial infinitesimal flexes.

See inf_flexes() for possible keywords.

Definitions

Infinitesimal flex

Parameters:: vertex_order – A list of vertices, providing the ordering for the entries of the infinitesimal flexes. If None, the list from Graph.vertex_list() is taken.
Return type:: list[MutableDenseMatrix]

Examples

>>> import pyrigi.graphDB as graphs
>>> F = Framework.Circular(graphs.CompleteBipartite(3, 3))
>>> F.nontrivial_inf_flexes()
[Matrix([
[       3/2],
[-sqrt(3)/2],
[         1],
[         0],
[         0],
[         0],
[       3/2],
[-sqrt(3)/2],
[         1],
[         0],
[         0],
[         0]])]

plot(plot_style=None, **kwargs)[source]¶

Plot the framework.

The framework can be plotted only if its dimension is less than 3. For plotting a projection of a higher dimensional framework, use plot2D() or plot3D() instead. For various formatting options, see PlotStyle.

Return type:: None
Parameters:: plot_style (PlotStyle)

plot2D(plot_style=None, projection_matrix=None, random_seed=None, coordinates=None, inf_flex=None, stress=None, edge_colors_custom=None, stress_label_positions=None, arc_angles_dict=None, **kwargs)[source]¶

Plot the framework in 2D.

If the framework is in dimensions higher than 2 and projection_matrix with coordinates are None, a random projection matrix containing two orthonormal vectors is generated and used for projection into 2D. For various formatting options, see PlotStyle. Only coordinates or projection_matrix parameter can be used, not both!

Parameters:

plot_style (PlotStyle) – An instance of the PlotStyle class that defines the visual style for plotting, see PlotStyle for more details.
projection_matrix (Matrix) – The matrix used for projecting the realization when the dimension is greater than 2. The matrix must have dimensions (2, dim), where dim is the dimension of the framework. If None, a random projection matrix is generated.
random_seed (int) – The random seed used for generating the projection matrix.
coordinates (Sequence[int]) – Indices of two coordinates to which the framework is projected.
inf_flex (int | InfFlex) – Optional parameter for plotting a given infinitesimal flex. The standard input format is a Matrix that is the output of e.g. the method inf_flexes(). Alternatively, an int can be specified to directly choose the 0,1,2,…-th nontrivial infinitesimal flex (according to the method nontrivial_inf_flexes()) for plotting. For these input types, it is important to use the same vertex order as the one from Graph.vertex_list(). If the vertex order needs to be specified, a dict[Vertex, Sequence[Number]] can be provided, which maps the vertex labels to vectors (i.e. a sequence of coordinates).
stress (int | Stress) – Optional parameter for plotting a given equilibrium stress. The standard input format is a Matrix that is the output of e.g. the method stresses(). Alternatively, an int can be specified to directly choose the 0,1,2,…-th equilibrium stress (according to the method stresses()) for plotting. For these input types, it is important to use the same edge order as the one from Graph.edge_list(). If the edge order needs to be specified, a Dict[Edge, Number] can be provided, which maps the edges to numbers (i.e. coordinates).
edge_colors_custom (Sequence[Sequence[Edge]] | dict[str, Sequence[Edge]]) – Optional parameter to specify the colors of edges. It can be a Sequence[Sequence[Edge]] to define groups of edges with the same color or a dict[str, Sequence[Edge]] where the keys are color strings and the values are lists of edges. The ommited edges are given the value plot_style.edge_color.
stress_label_positions (dict[DirectedEdge, float]) – Dictionary specifying the position of stress labels along the edges. Keys are DirectedEdge objects, and values are floats (e.g., 0.5 for midpoint). Ommited edges are given the value 0.5.
arc_angles_dict (Sequence[float] | dict[DirectedEdge, float]) – Optional parameter to specify custom arc angle for edges. Can be a Sequence[float] or a dict[Edge, float] where values define the curvature angle of edges in radians.

Return type:

None

Examples

>>> from pyrigi import Graph, Framework
>>> G = Graph([(0,1), (1,2), (2,3), (0,3), (0,2), (1,3), (0,4)])
>>> F = Framework(G, {0:(0,0), 1:(1,0), 2:(1,2), 3:(0,1), 4:(-1,0)})
>>> from pyrigi import PlotStyle2D
>>> style = PlotStyle2D(vertex_color="green", edge_color="blue")
>>> F.plot2D(plot_style=style)

Use keyword arguments

>>> F.plot2D(vertex_color="red", edge_color="black", vertex_size=500)

Specify stress and its labels positions

>>> stress_label_positions = {(0, 1): 0.7, (1, 2): 0.2}
>>> F.plot2D(stress=0, stress_label_positions=stress_label_positions)

Specify infinitesimal flex

>>> F.plot2D(inf_flex=0)

Use both stress and infinitesimal flex

>>> F.plot2D(stress=0, inf_flex=0)

Use custom edge colors

>>> edge_colors = {'red': [(0, 1), (1, 2)], 'blue': [(2, 3), (0, 3)]}
>>> F.plot2D(edge_colors_custom=edge_colors)

The following is just to close all figures after running the example:

>>> import matplotlib.pyplot
>>> matplotlib.pyplot.close("all")

plot3D(plot_style=None, projection_matrix=None, random_seed=None, coordinates=None, inf_flex=None, stress=None, edge_colors_custom=None, stress_label_positions=None, **kwargs)[source]¶

Plot the provided framework in 3D.

If the framework is in a dimension higher than 3 and projection_matrix with coordinates are None, a random projection matrix containing three orthonormal vectors is generated and used for projection into 3D. For various formatting options, see PlotStyle. Only the parameter coordinates or projection_matrix can be used, not both at the same time.

Parameters:

plot_style (PlotStyle) – An instance of the PlotStyle class that defines the visual style for plotting, see PlotStyle for more details.
projection_matrix (Matrix) – The matrix used for projecting the realization when the dimension is greater than 3. The matrix must have dimensions (3, dim), where dim is the dimension of the framework. If None, a random projection matrix is generated.
random_seed (int) – The random seed used for generating the projection matrix.
coordinates (Sequence[int]) – Indices of two coordinates to which the framework is projected.
inf_flex (int | InfFlex) – Optional parameter for plotting a given infinitesimal flex. The standard input format is a Matrix that is the output of e.g. the method inf_flexes(). Alternatively, an int can be specified to directly choose the 0,1,2,…-th nontrivial infinitesimal flex (according to the method nontrivial_inf_flexes()) for plotting. For these input types, is important to use the same vertex order as the one from Graph.vertex_list(). If the vertex order needs to be specified, a dict[Vertex, Sequence[Number]] can be provided, which maps the vertex labels to vectors (i.e. a sequence of coordinates).
stress (int | Stress) – Optional parameter for plotting a given equilibrium stress. The standard input format is a Matrix that is the output of e.g. the method stresses(). Alternatively, an int can be specified to directly choose the 0,1,2,…-th equilibrium stress (according to the method stresses()) for plotting. For these input types, is important to use the same edge order as the one from Graph.edge_list(). If the edge order needs to be specified, a Dict[Edge, Number] can be provided, which maps the edges to numbers (i.e. coordinates).
edge_colors_custom (Sequence[Sequence[Edge]] | dict[str:Sequence[Edge]]) – Optional parameter to specify the colors of edges. It can be a Sequence[Sequence[Edge]] to define groups of edges with the same color or a dict[str, Sequence[Edge]] where the keys are color strings and the values are lists of edges. The ommited edges are given the value plot_style.edge_color.
stress_label_positions (dict[DirectedEdge, float]) – Dictionary specifying the position of stress labels along the edges. Keys are DirectedEdge objects, and values are floats (e.g., 0.5 for midpoint). Ommited edges are given the value 0.5.

Return type:

None

Examples

>>> from pyrigi import frameworkDB
>>> F = frameworkDB.Octahedron(realization="Bricard_plane")
>>> F.plot3D()

>>> from pyrigi import PlotStyle3D
>>> style = PlotStyle3D(vertex_color="green", edge_color="blue")
>>> F.plot3D(plot_style=style)

Use keyword arguments

>>> F.plot3D(vertex_color="red", edge_color="black", vertex_size=500)

Specify stress and its positions

>>> stress_label_positions = {(0, 2): 0.7, (1, 2): 0.2}
>>> F.plot3D(stress=0, stress_label_positions=stress_label_positions)

Specify infinitesimal flex

>>> F.plot3D(inf_flex=0)

Use both stress and infinitesimal flex

>>> F.plot3D(stress=0, inf_flex=0)

Use custom edge colors

>>> edge_colors = {'red': [(5, 1), (1, 2)], 'blue': [(2, 4), (4, 3)]}
>>> F.plot3D(edge_colors_custom=edge_colors)

The following is just to close all figures after running the example:

>>> import matplotlib.pyplot
>>> matplotlib.pyplot.close("all")

projected_realization(proj_dim=None, projection_matrix=None, random_seed=None, coordinates=None)[source]¶

Return the realization projected to a lower dimension and the projection matrix.

Parameters:

proj_dim (int) – The dimension to which the framework is projected. This is determined from projection_matrix if it is provided.
projection_matrix (MutableDenseMatrix) – The matrix used for projecting the placement of vertices. The matrix must have dimensions (proj_dim, dim), where dim is the dimension of the framework self. If None, a numerical random projection matrix is generated.
random_seed (int) – The random seed used for generating the projection matrix.
coordinates (Sequence[int]) – Indices of coordinates to which projection is applied. Providing the parameter overrides the previous ones.

Return type:

tuple[dict[Vertex, Point], MutableDenseMatrix]

Suggested Improvements

Generate random projection matrix over symbolic rationals.

realization(as_points=False, numerical=False)[source]¶

Return a copy of the realization.

Parameters:

as_points (bool) – If True, then the vertex positions type is pyrigi.data_type.Point, otherwise Matrix (default).
numerical (bool) – If True, the vertex positions are converted to floats.

Return type:

dict[Vertex, Point] | dict[Vertex, MutableDenseMatrix]

Examples

>>> F = Framework.Complete([(0,0), (1,0), (1,1)])
>>> F.realization(as_points=True)
{0: [0, 0], 1: [1, 0], 2: [1, 1]}
>>> F.realization()
{0: Matrix([
[0],
[0]]), 1: Matrix([
[1],
[0]]), 2: Matrix([
[1],
[1]])}

rescale(factor, inplace=True)[source]¶

Scale the framework.

Parameters:

factor (Number) – Scaling factor
inplace (bool) – If True (default), then this framework is translated. Otherwise, a new translated framework is returned.

Return type:

None | Framework

rigidity_matrix(vertex_order=None, edge_order=None)[source]¶

Construct the rigidity matrix of the framework.

Definitions

Rigidity matrix

Parameters:

vertex_order (Sequence[Vertex]) – A list of vertices, providing the ordering for the columns of the rigidity matrix. If none is provided, the list from Graph.vertex_list() is taken.
edge_order (Sequence[Edge]) – A list of edges, providing the ordering for the rows of the rigidity matrix. If none is provided, the list from Graph.edge_list() is taken.

Return type:

MutableDenseMatrix

Examples

>>> F = Framework.Complete([(0,0),(2,0),(1,3)])
>>> F.rigidity_matrix()
Matrix([
[-2,  0, 2,  0,  0, 0],
[-1, -3, 0,  0,  1, 3],
[ 0,  0, 1, -3, -1, 3]])

rigidity_matrix_rank()[source]¶

Return the rank of the rigidity matrix.

Return type:: int

Definitions

Rigidity matrix

Examples

>>> K4 = Framework.Complete([[0,0], [1,0], [1,1], [0,1]])
>>> K4.rigidity_matrix_rank()   # the complete graph is a circuit
5
>>> K4.delete_edge([0,1])
>>> K4.rigidity_matrix_rank()   # deleting a bar gives full rank
5
>>> K4.delete_edge([2,3])
>>> K4.rigidity_matrix_rank()   #so now deleting an edge lowers the rank
4

rotate2D(angle, inplace=True)[source]¶

Rotate the planar framework counterclockwise.

Parameters:

angle (float) – Rotation angle
inplace (bool) – If True (default), then this framework is rotated. Otherwise, a new rotated framework is returned.

Return type:

None | Framework

set_realization(realization)[source]¶

Change the realization of the framework.

Definitions

Realization

Parameters:: realization (dict[Vertex, Point]) – A realization of the underlying graph of the framework. It must contain all vertices from the underlying graph. Furthermore, all points in the realization need to be contained in \(\RR^d\) for \(d\) being the current dimension of the framework.
Return type:: None

Examples

>>> F = Framework.Complete([(0,0), (1,0), (1,1)])
>>> F.set_realization(
...     {vertex: (vertex, vertex + 1) for vertex in F.graph.vertex_list()}
... )
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0, 1, 2] and edges [[0, 1], [0, 2], [1, 2]]
Realization {0:(0, 1), 1:(1, 2), 2:(2, 3)}

set_vertex_pos(vertex, point)[source]¶

Change the coordinates of a single given vertex.

Parameters:

vertex (Vertex) – A vertex whose position is changed.
point (Point) – A new position of the vertex.

Return type:

None

Examples

>>> F = Framework.from_points([(0,0)])
>>> F.set_vertex_pos(0, (6,2))
>>> print(F)
Framework in 2-dimensional space consisting of:
Graph with vertices [0] and edges []
Realization {0:(6, 2)}

set_vertex_positions(subset_of_realization)[source]¶

Change the coordinates of vertices given by a dictionary.

Parameters:: subset_of_realization (dict[Vertex, Point])
Return type:: None

Examples

>>> F = Framework.Complete([(0,0),(0,0),(1,0),(1,0)])
>>> F.realization(as_points=True)
{0: [0, 0], 1: [0, 0], 2: [1, 0], 3: [1, 0]}
>>> F.set_vertex_positions({1:(0,1),3:(1,1)})
>>> F.realization(as_points=True)
{0: [0, 0], 1: [0, 1], 2: [1, 0], 3: [1, 1]}

set_vertex_positions_from_lists(vertices, points)[source]¶

Change the coordinates of a given list of vertices.

It is necessary that both lists have the same length. No vertex from vertices can be contained multiple times. We apply the method set_vertex_positions() to the corresponding pairs of vertices and points.

Parameters:

vertices (Sequence[Vertex])
points (Sequence[Point])

Return type:

None

Examples

>>> F = Framework.Complete([(0,0),(0,0),(1,0),(1,0)])
>>> F.realization(as_points=True)
{0: [0, 0], 1: [0, 0], 2: [1, 0], 3: [1, 0]}
>>> F.set_vertex_positions_from_lists([1,3], [(0,1),(1,1)])
>>> F.realization(as_points=True)
{0: [0, 0], 1: [0, 1], 2: [1, 0], 3: [1, 1]}

stress_matrix(stress, edge_order=None, vertex_order=None)[source]¶

Construct the stress matrix of a stress.

Definitions

Stress Matrix

Parameters:

stress (Stress) – A stress of the framework given as a vector.
edge_order (Sequence[Edge]) – A list of edges, providing the ordering of edges in stress. If None, Graph.edge_list() is assumed.
vertex_order (Sequence[Vertex]) – Specification of row/column order of the stress matrix. If None, Graph.vertex_list() is assumed.

Return type:

MutableDenseMatrix

Examples

>>> G = Graph([[0,1],[0,2],[0,3],[1,2],[2,3],[3,1]])
>>> pos = {0: (0, 0), 1: (0,1), 2: (-1,-1), 3: (1,-1)}
>>> F = Framework(G, pos)
>>> omega = [-8, -4, -4, 2, 2, 1]
>>> F.stress_matrix(omega)
Matrix([
[-16,  8,  4,  4],
[  8, -4, -2, -2],
[  4, -2, -1, -1],
[  4, -2, -1, -1]])

stresses(edge_order=None, numerical=False, tolerance=1e-09)[source]¶

Return a basis of the space of equilibrium stresses.

Definitions

Equilibrium stress

Parameters:

edge_order (Sequence[Edge]) – A list of edges, providing the ordering for the entries of the stresses. If none is provided, the list from Graph.edge_list() is taken.
numerical (bool) – Determines whether the output is symbolic (default) or numerical.
tolerance (float) – Used tolerance when computing the stresses numerically.

Return type:

list[MutableDenseMatrix] | list[list[float]]

Examples

>>> G = Graph([[0,1],[0,2],[0,3],[1,2],[2,3],[3,1]])
>>> pos = {0: (0, 0), 1: (0,1), 2: (-1,-1), 3: (1,-1)}
>>> F = Framework(G, pos)
>>> F.stresses()
[Matrix([
[-8],
[-4],
[-4],
[ 2],
[ 2],
[ 1]])]

to_tikz(vertex_style='fvertex', edge_style='edge', label_style='labelsty', figure_opts='', vertex_in_labels=False, vertex_out_labels=False, default_styles=True)[source]¶

Create a TikZ code for the framework.

The framework must have dimension 2. For using it in LaTeX you need to use the tikz package. For more examples on formatting options, see also Graph.to_tikz().

Parameters:

vertex_style (str | dict[slice(<class ‘str’>, collections.abc.Sequence[TypeAliasForwardRef(’Vertex’)], None)]) – If a single style is given as a string, then all vertices get this style. If a dictionary from styles to a list of vertices is given, vertices are put in style accordingly. The vertices missing in the dictionary do not get a style.
edge_style (str | dict[slice(<class ‘str’>, collections.abc.Sequence[TypeAliasForwardRef(’Edge’)], None)]) – If a single style is given as a string, then all edges get this style. If a dictionary from styles to a list of edges is given, edges are put in style accordingly. The edges missing in the dictionary do not get a style.
label_style (str) – The style for labels that are placed next to vertices.
figure_opts (str) – Options for the tikzpicture environment.
vertex_in_labels (bool) – A bool on whether vertex names should be put as labels on the vertices.
vertex_out_labels (bool) – A bool on whether vertex names should be put next to vertices.
default_styles (bool) – A bool on whether default style definitions should be put to the options.

Return type:

str

Examples

>>> G = Graph([(0, 1), (1, 2), (2, 3), (0, 3)])
>>> F=Framework(G,{0: [0, 0], 1: [1, 0], 2: [1, 1], 3: [0, 1]})
>>> print(F.to_tikz())
\begin{tikzpicture}[fvertex/.style={circle,inner sep=0pt,minimum size=3pt,fill=white,draw=black,double=white,double distance=0.25pt,outer sep=1pt},edge/.style={line width=1.5pt,black!60!white}]
   \node[fvertex] (0) at (0, 0) {};
   \node[fvertex] (1) at (1, 0) {};
   \node[fvertex] (2) at (1, 1) {};
   \node[fvertex] (3) at (0, 1) {};
   \draw[edge] (0) to (1) (0) to (3) (1) to (2) (2) to (3);
\end{tikzpicture}

>>> print(F.to_tikz(vertex_in_labels=True))
\begin{tikzpicture}[fvertex/.style={circle,inner sep=1pt,minimum size=3pt,fill=white,draw=black,double=white,double distance=0.25pt,outer sep=1pt,font=\scriptsize},edge/.style={line width=1.5pt,black!60!white}]
   \node[fvertex] (0) at (0, 0) {$0$};
   \node[fvertex] (1) at (1, 0) {$1$};
   \node[fvertex] (2) at (1, 1) {$2$};
   \node[fvertex] (3) at (0, 1) {$3$};
   \draw[edge] (0) to (1) (0) to (3) (1) to (2) (2) to (3);
\end{tikzpicture}

translate(vector, inplace=True)[source]¶

Translate the framework.

Parameters:

vector (Point | Matrix) – Translation vector
inplace (bool) – If True (default), then this framework is translated. Otherwise, a new translated framework is returned.

Return type:

None | Framework

trivial_inf_flexes(vertex_order=None)[source]¶

Return a basis of the vector subspace of trivial infinitesimal flexes.

Definitions

Trivial infinitesimal flexes

Parameters:: vertex_order (Sequence[Vertex]) – A list of vertices, providing the ordering for the entries of the infinitesimal flexes.
Return type:: list[MutableDenseMatrix]

Examples

>>> F = Framework.Complete([(0,0), (2,0), (0,2)])
>>> F.trivial_inf_flexes()
[Matrix([
[1],
[0],
[1],
[0],
[1],
[0]]), Matrix([
[0],
[1],
[0],
[1],
[0],
[1]]), Matrix([
[ 0],
[ 0],
[ 0],
[ 2],
[-2],
[ 0]])]