basalt package

Submodules

basalt.topology module

Copyright (C) 2019 Blue Brain Project

This file is part of Basalt distributed under the terms of the GNU Lesser General Public License. See top-level LICENSE file for details.

basalt.topology.vertex(name, type, serialization=None, plural=None, default_payload=True)[source]

Declare a vertex type

Parameters

  • name (str) – vertex name

  • type (enum) – enum value

  • serialization –

    it can take several values:

    • "pickle": whenever an object will be attached to a vertex of this type, the pickle module will be used to serialize/deserialize it.

    • None (default): payload specified when creating a vertex if passed as is to the low level graph, that only accepts numpy.ndarray(shape=(N,), dtype=numpy.byte)

  • plural (string) – overwrite default plural (name + ‘s’)

  • default_payload (bool) – whether new vertex has an empty payload (default: True)

basalt.topology.edge(head, tail, name=None, plural=None, serialization=None, default_payload=True)[source]

Directive to declare an edge between 2 type of vertices

Parameters

  • head (enum value) – vertex type at one end of the edge

  • tail (enum value) – vertex type at the other end of the edge

  • name (str) – edge name, default is the type of the edge tail

  • plural (str) – overwrite default plural (name + ‘s’)

  • serialization – optional serialization method. see vertex()

  • default_payload (bool) – whether new edge has an empty payload (default: True)

class basalt.topology.Graph(graph=None, path=None, **kwargs)[source]

Bases: object

commit()[source]

See basalt.Graph.commit()

edges

See basalt.Graph.edges()

edges_types = {}
classmethod from_graph(graph)[source]

Create a new graph instance

Parameters

graph (basalt.UndirectedGraph or DirectedGraph) – low-level graph instance

classmethod from_path(path, **kwargs)[source]

Create a new graph instance

Parameters

  • path (str) – the path to basalt database on filesystem. The database is created if path does not exists

  • kwargs – additional arguments given to the inner graph constructor.

settings = {'directed': False}
statistics()[source]

See basalt.Graph.statistics()

vertex_types = {}
vertices

See basalt.Graph.vertices()

basalt.topology.vertex(name, type, serialization=None, plural=None, default_payload=True)[source]

Declare a vertex type

Parameters

  • name (str) – vertex name

  • type (enum) – enum value

  • serialization –

    it can take several values:

    • "pickle": whenever an object will be attached to a vertex of this type, the pickle module will be used to serialize/deserialize it.

    • None (default): payload specified when creating a vertex if passed as is to the low level graph, that only accepts numpy.ndarray(shape=(N,), dtype=numpy.byte)

  • plural (string) – overwrite default plural (name + ‘s’)

  • default_payload (bool) – whether new vertex has an empty payload (default: True)

basalt.topology.edge(head, tail, name=None, plural=None, serialization=None, default_payload=True)[source]

Directive to declare an edge between 2 type of vertices

Parameters

  • head (enum value) – vertex type at one end of the edge

  • tail (enum value) – vertex type at the other end of the edge

  • name (str) – edge name, default is the type of the edge tail

  • plural (str) – overwrite default plural (name + ‘s’)

  • serialization – optional serialization method. see vertex()

  • default_payload (bool) – whether new edge has an empty payload (default: True)

basalt.topology.directed(value)[source]

Directive to declare whether the graph is directed or not (the default)

basalt.serialization module

Copyright (C) 2019 Blue Brain Project

This file is part of Basalt distributed under the terms of the GNU Lesser General Public License. See top-level LICENSE file for details.

class basalt.serialization.BasaltPayloadSerialization(payload_cls, default_payload)[source]

Bases: object

default_payload()[source]
deserialize(data)[source]
serialize(data)[source]
class basalt.serialization.NoneSerialization[source]

Bases: object

classmethod default_payload()[source]
classmethod deserialize(data)[source]
classmethod serialize(obj)[source]
class basalt.serialization.PickleSerialization[source]

Bases: object

classmethod default_payload()[source]
classmethod deserialize(obj)[source]
classmethod serialize(obj)[source]
basalt.serialization.serialization_method(name, default_payload)[source]

Module contents

Copyright (C) 2019 Blue Brain Project

This file is part of Basalt distributed under the terms of the GNU Lesser General Public License. See top-level LICENSE file for details.

basalt.default_config_file(path: str) → None

Helper function to write a JSON file containing the default basalt database configuration.

Parameters

type (str) – path to JSON file to write

class basalt.DirectedGraph

Bases: pybind11_builtins.pybind11_object

Directed Connectivity Graph

commit(self: basalt._basalt.DirectedGraph) → None

Flush pending changes on disk

Raises

RuntimeException – uppon error

>>> graph.vertices.add((1, 42))
>>> graph.commit()
edges

Get wrapper around the edges of the graph

Returns

instance of Edges

statistics(self: basalt._basalt.DirectedGraph) → str

Get wrapper around the vertices of the graph

Returns

instance of Vertices

vertices

Get wrapper around the vertices of the graph

Returns

instance of Vertices

class basalt.Edges

Bases: pybind11_builtins.pybind11_object

Manage edges of the graph

An edge is made of 2 distinct vertices

Optionally, a byte-array can be attached to an edge.

Both vertices must exist prior creation of an edge:

>>> graph.vertices.clear()
>>> v1, v2 = [(0, 1), (0, 2)]
>>> graph.vertices.add(v1)
>>> graph.edges.add(v1, v2)
Traceback (most recent call last):
  ...
RuntimeError: Missing vertex (0:2)

Both ends of an edge must exist first:

>>> graph.vertices.clear()
>>> graph.vertices.add(v1)
>>> graph.vertices.add(v2)
>>> graph.edges.add(v1, v2)
>>> len(graph.edges)
1

if the graph is undirected, then the 2 possible uids represents the same edge:

>>> (v1, v2) in graph.edges
True
>>> (v2, v1) in graph.edges
True

It is possible to iterate over the edges of the graph. Note that every edge appears in both direction:

>>> for edge in sorted(graph.edges):
...   print(edge)
((0, 1), (0, 2))
((0, 2), (0, 1))
add(*args, **kwargs)

Overloaded function.

  1. add(self: basalt._basalt.Edges, vertex1: Tuple[int, int], vertex2: Tuple[int, int], commit: bool = False) -> None

    Add or overwrite an edge

    Args:

    vertex1(tuple): first vertex identifier. vertex2(tuple): second vertex identifier. commit(bool): whether uncommitted operations should be flushed or not.

    >>> graph.vertices.clear()
>>> v1, v2 = [(0, 1), (0, 2)]
>>> graph.vertices.add(v1)
>>> graph.vertices.add(v2)
>>> graph.edges.add(v1, v2)

  2. add(self: basalt._basalt.Edges, vertex1: Tuple[int, int], vertex2: Tuple[int, int], data: numpy.ndarray[int8], commit: bool = False) -> None

    Add or overwrite an edge with a payload attached

    Args:

    vertex1(tuple): first vertex identifier. vertex2(tuple): second vertex identifier. payload(np.array(dtype=np.byte)): array of bytes. commit(bool): whether uncommitted operations should be flushed or not.

    >>> graph.vertices.clear()
>>> v1, v2 = [(0, 1), (0, 2)]
>>> graph.vertices.add(v1)
>>> graph.vertices.add(v2)
>>> graph.edges.add(v1, v2, np.arange(10, dtype=np.byte))

  3. add(self: basalt._basalt.Edges, vertex: Tuple[int, int], type: int, vertices: numpy.ndarray[uint64], commit: bool = False, create_vertices: bool = False) -> None

    Create an edge between a vertex and a list of other vertices

    Args:

    vertex(tuple): vertex from which all edges to create start. type(int): type of target vertices to connect to (the same of all target vertices). vertices(np.array(dtype=np.int64)): array of target vertices identifiers. create_vertices(bool): wether the target vertices are also created or not

    Any prior vertices with the same identifiers will be overwritten.

    commit(bool): whether uncommitted operations should be flushed or not.

  4. add(self: basalt._basalt.Edges, vertex: Tuple[int, int], type: int, vertices: numpy.ndarray[uint64], vertex_payloads: list, commit: bool = False, create_vertices: bool = False) -> None

    Create an edge between a vertex and a list of other vertices that are also created

    Args:

    vertex(tuple): vertex from which all edges to create start. type(int): type of target vertices to connect to (the same of all target vertices). vertices(np.array(dtype=np.int64)): array of target vertices identifiers. vertex_payloads(list of np.array(dtype=np.int64)): payload of target vertices. create_vertices(bool): wether the target vertices are also created or not.

    Any prior vertices with the same identifiers will be overwritten.

    commit(bool): whether uncommitted operations should be flushed or not.

discard(*args, **kwargs)

Overloaded function.

  1. discard(self: basalt._basalt.Edges, edge: Tuple[Tuple[int, int], Tuple[int, int]], commit: bool = False) -> None

    Remove edge between 2 vertices

    Args:

    edge(tuple): edge unique identifier to remove. commit(bool): whether uncommitted operations should be flushed or not.

    >>> v1, v2 = (0, 1), (0, 2)
>>> graph.edges.discard((v1, v2))

  2. discard(self: basalt._basalt.Edges, vertex: Tuple[int, int], commit: bool = False) -> int

    Remove edges connected to a given vertex

    Args:

    vertex(tuple): vertex unique identifier. commit(bool): whether uncommitted operations should be flushed or not.

  3. discard(self: basalt._basalt.Edges, vertex: Tuple[int, int], filter: int, commit: bool = False) -> int

    Remove edges starting from a given vertex and where the vertex on the other end is of a certain type

    Args:

    vertex(tuple): vertex unique identifier from where the edge starts. type(int): type of the other end of the edge. commit(bool): whether uncommitted operations should be flushed or not

get(*args, **kwargs)

Overloaded function.

  1. get(self: basalt._basalt.Edges, edge: Tuple[Tuple[int, int], Tuple[int, int]]) -> object

    Get payload associated to an edge

    Args:

    edge(tuple): edge unique identifier.

    Returns:

    None is edge does not exist or does not have an associated payload. a np.array(dtype=np.byte) array otherwise.

    Raises:

    KeyError: if edge does not exist

    >>> graph.vertices.clear()
>>> v1, v2 = [(0, 1), (0, 2)]
>>> graph.vertices.add(v1)
>>> graph.vertices.add(v2)
>>> graph.edges.add(v1, v2, np.arange(10, dtype=np.byte))
>>> graph.edges.get((v1, v2))
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int8)
>>> graph.edges.get((v1, (0, 3)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError:

  2. get(self: basalt._basalt.Edges, vertex: Tuple[int, int]) -> List[Tuple[int, int]]

    Get all vertices connected to one vertex

    Args:

    vertex(tuple): vertex unique identifier.

    Returns:

    vector of vertices (usable like a list)

    >>> graph.vertices.clear()
>>> v1, v2, v3 = [(0, 1), (0, 2), (1, 3)]
>>> _ = [graph.vertices.add(v) for v in [v1, v2, v3]]
>>> graph.edges.add(v1, v2)
>>> graph.edges.add(v1, v3)
>>> for v in graph.edges.get(v1):
...   print(v)
(0, 2)
(1, 3)

  3. get(self: basalt._basalt.Edges, vertex: Tuple[int, int], filter: int) -> List[Tuple[int, int]]

    Get vertices of a certain type connected to one vertex

    Args:

    vertex(tuple): vertex unique identifier. filter(int): vertex type.

    Returns:

    vector of vertices (usable like a list).

    >>> graph.vertices.clear()
>>> v1, v2, v3 = [(0, 1), (0, 2), (1, 3)]
>>> _ = [graph.vertices.add(v) for v in [v1, v2, v3]]
>>> graph.edges.add(v1, v2)
>>> graph.edges.add(v1, v3)
>>> for v in graph.edges.get(v1, 0):
...   print(v)
(0, 2)
basalt.make_id(type: int, id: int) → Tuple[int, int]

Helper function to create vertex identifier

Parameters

  • type (int) – vertex type

  • id (int) – vertex identifier

Returns

A tuple of 2 elements providing the type and id

>>> basalt.make_id(42, 43)
(42, 43)
class basalt.Status

Bases: pybind11_builtins.pybind11_object

Provide result of one or several graph operations

code

operation status code, 0 means success.

Type

int

message

optional message

Type

str

To use it:

>>> status = basalt.Status(code=42)
>>> status.code
42
>>> if status:
...   print('ok')
... else:
...   print('oops')
...
oops

A message for humans can be also specified

>>> status = basalt.Status(code=42, message="the answer to every question")
>>> status.message
'the answer to every question'
code
message
raise_on_error(self: basalt._basalt.Status) → basalt._basalt.Status

Ensure status is ok

Raises

RuntimeException – whenever status code is different than 0

Returns

This instance

>>> basalt.Status(code=0, message="all good").raise_on_error()
Status(code=0, message="all good")
>>> basalt.Status(code=42, message="actually...").raise_on_error()
Traceback (most recent call last):
    ...
RuntimeError: actually...
class basalt.UndirectedGraph

Bases: pybind11_builtins.pybind11_object

Undirected Connectivity Graph

commit(self: basalt._basalt.UndirectedGraph) → None

Flush pending changes on disk

Raises

RuntimeException – uppon error

>>> graph.vertices.add((1, 42))
>>> graph.commit()
edges

Get wrapper around the edges of the graph

Returns

instance of Edges

statistics(self: basalt._basalt.UndirectedGraph) → str

Get RocksDB usage statistics as a string

vertices

Get wrapper around the vertices of the graph

Returns

instance of Vertices

class basalt.Vertices

Bases: pybind11_builtins.pybind11_object

Manage vertices of the graph

A vertex is a tuple made of 2 integers representing the vertex type and identifier.

Optionally, a byte-array can be attached to a vertex.

>>> graph.vertices.clear()
>>> graph.vertices.add((0, 1))
>>> graph.vertices.add((0, 2))
>>> len(graph.vertices)
2

>>> (0, 1) in graph.vertices
True
>>> (0, 3) not in graph.vertices
True
>>> for vertex in graph.vertices:
...   print(vertex)
(0, 1)
(0, 2)

>>> graph.vertices.discard((0, 3))
>>> graph.vertices.discard((0, 1))
>>> (0, 1) in graph.vertices
False
add(*args, **kwargs)

Overloaded function.

  1. add(self: basalt._basalt.Vertices, vertex: Tuple[int, int], commit: bool = False) -> None

    Insert a vertex in the graph

    Args:

    vertex(tuple): vertex unique identifier. commit(bool): whether uncommitted operations should be flushed or not.

  2. add(self: basalt._basalt.Vertices, vertex: Tuple[int, int], data: numpy.ndarray[int8], commit: bool = False) -> None

    Insert a vertex in the graph

    Args:

    vertex(tuple): vertex unique identifier. data(numpy.array(dtype=numpy.byte)): payload attached to the vertex. commit(bool): whether uncommitted operations should be flushed or not.

  3. add(self: basalt._basalt.Vertices, types: numpy.ndarray[int32], ids: numpy.ndarray[uint64], payloads: list = [], commit: bool = False) -> None

    Insert several vertices in the graph all at once”,

    Args:

    types(np.array(dtype=np.int32): 1-dimensional array of vertex types. ids(np.array(dtype=np.int64)): 1-dimensional array of vertex identifiers. payloads: optional list of vertex payload. commit(bool): whether uncommitted operations should be flushed or not.

clear(self: basalt._basalt.Vertices, commit: bool = False) → None

Remove all vertices of the graph along with their edges

Parameters

commit (bool) – whether uncommitted operations should be flushed or not.

>>> graph.vertices.add((0, 1))
>>> graph.vertices.clear()
>>> len(graph.vertices)
0
count(self: basalt._basalt.Vertices, type: int) → int

Get number of vertices of a certain type

Parameters

type (int) – vertex type.

Returns

Number of vertices of the given type

discard(self: basalt._basalt.Vertices, vertex: Tuple[int, int], commit: bool = False) → None

Remove the given vertex if present

Parameters

  • type (int) – vertex type

  • id (int) – vertex identifier

get(self: basalt._basalt.Vertices, vertex: Tuple[int, int]) → object

Retrieve a vertex payload from the graph

Parameters

vertex (tuple) – vertex unique identifier.

Returns

vertex payload if vertex exists and has a payload, None otherwise.

>>> graph.vertices.add((0, 1), np.arange(10, dtype=np.byte))
>>> graph.vertices.add((0, 2))
>>> graph.vertices.get((0, 1))
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=int8)
>>> graph.vertices.get((0, 2)) is None
True