Errors

The Python API raises every failure the engine reports — an unreadable input file, an invalid args string, an option conflict, an unwritable output path — as InfomapError or one of its subclasses. The exception preserves the engine’s message. Catch the base class to handle any Infomap failure, or a subclass for targeted handling:

import infomap

try:
    result = infomap.run("network.net")
except infomap.NetworkParseError as error:
    print(f"Bad input file: {error}")
except infomap.InfomapError as error:
    print(f"Infomap failed: {error}")

Compatibility

Through 2.x, InfomapError inherits RuntimeError — the type the Python API raised for engine errors before the taxonomy existed — so existing except RuntimeError code keeps working. NotRunError additionally keeps ValueError in its MRO, the type the results-before-run guard raised previously. Plan for these legacy bases to detach in 3.0: catch InfomapError (or a subclass), not the legacy bases.

Errors that are not Infomap failures keep their standard Python types: invalid argument values passed to the Python API raise ValueError or TypeError as usual.

The taxonomy

exception infomap.InfomapError

Base class for errors raised by the Infomap engine or package.

Every error the engine reports – invalid arguments, option conflicts, flow-calculation failures, unwritable output files – is raised as this class or one of its subclasses. Inherits RuntimeError through 2.x for backwards compatibility.

exception infomap.NetworkParseError

The network input could not be read.

Raised by Infomap.read_file, Network.from_file, and infomap.run() with a file path, when the input file cannot be opened or its content cannot be parsed. Also raised from run() when an auxiliary input file (e.g. cluster_data) fails to open or parse.

exception infomap.NotRunError

Results were requested before the algorithm has run.

Raised by the exporters and integration helpers when they are handed an Infomap instance with no module assignments yet. Keeps ValueError in its MRO through 2.x because this guard previously raised ValueError.

exception infomap.StaleResultError

Node-level data was read from a Result after a re-run.

The C++ result tree is rebuilt on every run(), so node-level access on a Result created by an earlier run raises instead of reading the rebuilt tree. The eager scalars captured at run() time (codelength, module counts, …) stay valid on the stale Result.

Only a re-run of the engine the Result came from – an Infomap or a Network – invalidates it. Running a different engine leaves this Result alone.