Skip to content

HypergraphDB Class

hyperdb.hypergraph.HypergraphDB dataclass 

HypergraphDB(
    storage_file: Union[str, Path] = "my_hypergraph.hgdb",
    _v_data: Dict[str, Any] = dict(),
    _e_data: Dict[Tuple, Any] = dict(),
    _v_inci: Dict[str, Set[Tuple]] = (
        lambda: defaultdict(set)
    )(),
)

Bases: BaseHypergraphDB

Hypergraph database.

Attributes

all_v cached property 

all_v: List[str]

Return a list of all vertices in the hypergraph.

all_e cached property 

all_e: List[Tuple]

Return a list of all hyperedges in the hypergraph.

num_v cached property 

num_v: int

Return the number of vertices in the hypergraph.

num_e cached property 

num_e: int

Return the number of hyperedges in the hypergraph.

Functions

__post_init__ 

__post_init__()
Source code in hyperdb/hypergraph.py 
24
25
26
27
28
29
def __post_init__(self):
    assert isinstance(self.storage_file, (str, Path))
    if isinstance(self.storage_file, str):
        self.storage_file = Path(self.storage_file)
    if self.storage_file.exists():
        self.load(self.storage_file)

load 

load(storage_file: Path) -> dict

Load the hypergraph database from the storage file.

Source code in hyperdb/hypergraph.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
def load(self, storage_file: Path) -> dict:
    r"""
    Load the hypergraph database from the storage file.
    """
    try:
        with open(storage_file, "rb") as f:
            data = pkl.load(f)
        self._v_data = data.get("v_data", {})
        self._v_inci = data.get("v_inci", {})
        self._e_data = data.get("e_data", {})
        return True
    except Exception as e:
        return False

save 

save(storage_file: Path) -> dict

Save the hypergraph database to the storage file.

Source code in hyperdb/hypergraph.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def save(self, storage_file: Path) -> dict:
    r"""
    Save the hypergraph database to the storage file.
    """
    data = {
        "v_data": self._v_data,
        "v_inci": self._v_inci,
        "e_data": self._e_data,
    }
    try:
        with open(storage_file, "wb") as f:
            pkl.dump(data, f)
        return True
    except Exception as e:
        return False

v 

v(v_id: str, default: Any = None) -> dict

Return the vertex data.

Args: v_id (str): The vertex id. default (Any): The default value if the vertex does not exist.

Source code in hyperdb/hypergraph.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
def v(self, v_id: str, default: Any = None) -> dict:
    r"""
    Return the vertex data.

    Args:
        ``v_id`` (``str``): The vertex id.
        ``default`` (``Any``): The default value if the vertex does not exist.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    try:
        return self._v_data[v_id]
    except KeyError:
        return default

e 

e(
    e_tuple: Union[List, Set, Tuple], default: Any = None
) -> dict

Return the hyperedge data.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name). default (Any): The default value if the hyperedge does not exist.

Source code in hyperdb/hypergraph.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def e(self, e_tuple: Union[List, Set, Tuple], default: Any = None) -> dict:
    r"""
    Return the hyperedge data.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
        ``default`` (``Any``): The default value if the hyperedge does not exist.
    """
    assert isinstance(
        e_tuple, (set, list, tuple)
    ), "The hyperedge must be a set, list, or tuple of vertex ids."
    e_tuple = self.encode_e(e_tuple)
    try:
        return self._e_data[e_tuple]
    except KeyError:
        return default

encode_e 

encode_e(e_tuple: Union[List, Set, Tuple]) -> Tuple

Sort and check the hyperedge tuple.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).

Source code in hyperdb/hypergraph.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def encode_e(self, e_tuple: Union[List, Set, Tuple]) -> Tuple:
    r"""
    Sort and check the hyperedge tuple.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    tmp = sorted(list(set(e_tuple)))
    for v_id in tmp:
        assert isinstance(v_id, Hashable), "The vertex id must be hashable."
        assert (
            v_id in self._v_data
        ), f"The vertex {v_id} does not exist in the hypergraph."
    return tuple(tmp)

add_v 

add_v(v_id: Any, v_data: Optional[Dict] = None)

Add a vertex to the hypergraph.

Args: v_id (Any): The vertex id. v_data (dict, optional): The vertex data.

Source code in hyperdb/hypergraph.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def add_v(self, v_id: Any, v_data: Optional[Dict] = None):
    r"""
    Add a vertex to the hypergraph.

    Args:
        ``v_id`` (``Any``): The vertex id.
        ``v_data`` (``dict``, optional): The vertex data.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    if v_data is not None:
        assert isinstance(v_data, dict), "The vertex data must be a dictionary."
    else:
        v_data = {}
    if v_id not in self._v_data:
        self._v_data[v_id] = v_data
        self._v_inci[v_id] = set()
    else:
        self._v_data[v_id].update(v_data)
    self._clear_cache()

add_e 

add_e(
    e_tuple: Union[List, Set, Tuple],
    e_data: Optional[Dict] = None,
)

Add a hyperedge to the hypergraph.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name). e_data (dict, optional): The hyperedge data.

Source code in hyperdb/hypergraph.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def add_e(self, e_tuple: Union[List, Set, Tuple], e_data: Optional[Dict] = None):
    r"""
    Add a hyperedge to the hypergraph.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
        ``e_data`` (``dict``, optional): The hyperedge data.
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    if e_data is not None:
        assert isinstance(e_data, dict), "The hyperedge data must be a dictionary."
    else:
        e_data = {}
    e_tuple = self.encode_e(e_tuple)
    if e_tuple not in self._e_data:
        self._e_data[e_tuple] = e_data
        for v in e_tuple:
            self._v_inci[v].add(e_tuple)
    else:
        self._e_data[e_tuple].update(e_data)
    self._clear_cache()

remove_v 

remove_v(v_id: Any)

Remove a vertex from the hypergraph.

Args: v_id (Any): The vertex id.

Source code in hyperdb/hypergraph.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
def remove_v(self, v_id: Any):
    r"""
    Remove a vertex from the hypergraph.

    Args:
        ``v_id`` (``Any``): The vertex id.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    assert (
        v_id in self._v_data
    ), f"The vertex {v_id} does not exist in the hypergraph."
    del self._v_data[v_id]
    old_e_tuples, new_e_tuples = [], []
    for e_tuple in self._v_inci[v_id]:
        new_e_tuple = self.encode_e(set(e_tuple) - {v_id})
        if len(new_e_tuple) >= 2:
            # todo: maybe new e tuple existing in hg, need to merge to hyperedge information
            self._e_data[new_e_tuple] = deepcopy(self._e_data[e_tuple])
        del self._e_data[e_tuple]
        old_e_tuples.append(e_tuple)
        new_e_tuples.append(new_e_tuple)
    del self._v_inci[v_id]
    for old_e_tuple, new_e_tuple in zip(old_e_tuples, new_e_tuples):
        for _v_id in old_e_tuple:
            if _v_id != v_id:
                self._v_inci[_v_id].remove(old_e_tuple)
                if len(new_e_tuple) >= 2:
                    self._v_inci[_v_id].add(new_e_tuple)
    self._clear_cache()

remove_e 

remove_e(e_tuple: Union[List, Set, Tuple])

Remove a hyperedge from the hypergraph.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).

Source code in hyperdb/hypergraph.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def remove_e(self, e_tuple: Union[List, Set, Tuple]):
    r"""
    Remove a hyperedge from the hypergraph.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    e_tuple = self.encode_e(e_tuple)
    assert (
        e_tuple in self._e_data
    ), f"The hyperedge {e_tuple} does not exist in the hypergraph."
    for v in e_tuple:
        self._v_inci[v].remove(e_tuple)
    del self._e_data[e_tuple]
    self._clear_cache()

update_v 

update_v(v_id: Any, v_data: dict)

Update the vertex data.

Args: v_id (Any): The vertex id. v_data (dict): The vertex data.

Source code in hyperdb/hypergraph.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def update_v(self, v_id: Any, v_data: dict):
    r"""
    Update the vertex data.

    Args:
        ``v_id`` (``Any``): The vertex id.
        ``v_data`` (``dict``): The vertex data.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    assert isinstance(v_data, dict), "The vertex data must be a dictionary."
    assert (
        v_id in self._v_data
    ), f"The vertex {v_id} does not exist in the hypergraph."
    self._v_data[v_id].update(v_data)
    self._clear_cache()

update_e 

update_e(e_tuple: Union[List, Set, Tuple], e_data: dict)

Update the hyperedge data.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name). e_data (dict): The hyperedge data.

Source code in hyperdb/hypergraph.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
def update_e(self, e_tuple: Union[List, Set, Tuple], e_data: dict):
    r"""
    Update the hyperedge data.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
        ``e_data`` (``dict``): The hyperedge data.
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    assert isinstance(e_data, dict), "The hyperedge data must be a dictionary."
    e_tuple = self.encode_e(e_tuple)
    assert (
        e_tuple in self._e_data
    ), f"The hyperedge {e_tuple} does not exist in the hypergraph."
    self._e_data[e_tuple].update(e_data)
    self._clear_cache()

has_v 

has_v(v_id: Any) -> bool

Check if the vertex exists.

Args: v_id (Any): The vertex id.

Source code in hyperdb/hypergraph.py 
275
276
277
278
279
280
281
282
283
def has_v(self, v_id: Any) -> bool:
    r"""
    Check if the vertex exists.

    Args:
        ``v_id`` (``Any``): The vertex id.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    return v_id in self._v_data

has_e 

has_e(e_tuple: Union[List, Set, Tuple]) -> bool

Check if the hyperedge exists.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).

Source code in hyperdb/hypergraph.py 
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
def has_e(self, e_tuple: Union[List, Set, Tuple]) -> bool:
    r"""
    Check if the hyperedge exists.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    try:
        e_tuple = self.encode_e(e_tuple)
    except AssertionError:
        return False
    return e_tuple in self._e_data

degree_v 

degree_v(v_id: Any) -> int

Return the degree of the vertex.

Args: v_id (Any): The vertex id.

Source code in hyperdb/hypergraph.py 
301
302
303
304
305
306
307
308
309
310
311
312
def degree_v(self, v_id: Any) -> int:
    r"""
    Return the degree of the vertex.

    Args:
        ``v_id`` (``Any``): The vertex id.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    assert (
        v_id in self._v_data
    ), f"The vertex {v_id} does not exist in the hypergraph."
    return len(self._v_inci[v_id])

degree_e 

degree_e(e_tuple: Union[List, Set, Tuple]) -> int

Return the degree of the hyperedge.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).

Source code in hyperdb/hypergraph.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
def degree_e(self, e_tuple: Union[List, Set, Tuple]) -> int:
    r"""
    Return the degree of the hyperedge.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    e_tuple = self.encode_e(e_tuple)
    assert (
        e_tuple in self._e_data
    ), f"The hyperedge {e_tuple} does not exist in the hypergraph."
    return len(e_tuple)

nbr_e_of_v 

nbr_e_of_v(v_id: Any) -> list

Return the incident hyperedges of the vertex.

Args: v_id (Any): The vertex id.

Source code in hyperdb/hypergraph.py 
330
331
332
333
334
335
336
337
338
339
340
341
def nbr_e_of_v(self, v_id: Any) -> list:
    r"""
    Return the incident hyperedges of the vertex.

    Args:
        ``v_id`` (``Any``): The vertex id.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    assert (
        v_id in self._v_data
    ), f"The vertex {v_id} does not exist in the hypergraph."
    return set(self._v_inci[v_id])

nbr_v_of_e 

nbr_v_of_e(e_tuple: Union[List, Set, Tuple]) -> list

Return the incident vertices of the hyperedge.

Args: e_tuple (Union[List, Set, Tuple]): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).

Source code in hyperdb/hypergraph.py 
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
def nbr_v_of_e(self, e_tuple: Union[List, Set, Tuple]) -> list:
    r"""
    Return the incident vertices of the hyperedge.

    Args:
        ``e_tuple`` (``Union[List, Set, Tuple]``): The hyperedge tuple: (v1_name, v2_name, ..., vn_name).
    """
    assert isinstance(
        e_tuple, (list, set, tuple)
    ), "The hyperedge must be a list, set, or tuple of vertex ids."
    e_tuple = self.encode_e(e_tuple)
    assert (
        e_tuple in self._e_data
    ), f"The hyperedge {e_tuple} does not exist in the hypergraph."
    return set(e_tuple)

nbr_v 

nbr_v(v_id: Any, exclude_self=True) -> list

Return the neighbors of the vertex.

Args: v_id (Any): The vertex id.

Source code in hyperdb/hypergraph.py 
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
def nbr_v(self, v_id: Any, exclude_self=True) -> list:
    r"""
    Return the neighbors of the vertex.

    Args:
        ``v_id`` (``Any``): The vertex id.
    """
    assert isinstance(v_id, Hashable), "The vertex id must be hashable."
    assert (
        v_id in self._v_data
    ), f"The vertex {v_id} does not exist in the hypergraph."
    nbrs = set()
    for e_tuple in self._v_inci[v_id]:
        nbrs.update(e_tuple)
    if exclude_self:
        nbrs.remove(v_id)
    return set(nbrs)