The stateful Infomap class¶

How-to

At a glance

The infomap.Infomap class is the stateful entry point: build a network with the add_* verbs, then call run() for an immutable Result. In new code, prefer infomap.run() for one-shot use and Network for incremental construction. Existing Infomap code keeps working essentially unchanged (see Removed accessors for the few exceptions).

When to use it¶

The functional infomap.run() and the Network builder cover most needs. Reach for the stateful Infomap class when you want to keep one configured object around and run it repeatedly. Also reach for it when you maintain code written against the original API. Internally it composes a Network and an Options over the same engine boundary. Its building verbs and its results are thus identical to the functional path.

infomap.run() is the canonical entry point. It accepts any input – including a prebuilt Network or a stateful Infomap instance. This makes net.run(**kw) and im.run(**kw) thin conveniences equivalent to infomap.run(net, **kw) / infomap.run(im, **kw). All three take the same keywords (the five common-tier options directly, everything else via options=) and return the same Result.

from infomap import Infomap

im = Infomap(seed=123, num_trials=10)
im.add_link(0, 1)
im.add_link(1, 2)
im.add_link(2, 0)

result = im.run()          # returns an immutable Result
print(result.codelength)
print(result.modules())

1.5849625007211494
{0: 1, 1: 1, 2: 1}

im.run() returns the same Result the functional API returns. The on-instance result accessors (im.get_modules(), im.codelength, im.nodes) still work and read from that result, but they are deprecated and leave in 3.0. Read the equivalently named members off the returned Result instead. Mind the shape shift: im.modules is a property, while result.modules() is a method. These accessors emit a DeprecationWarning, which Python shows by default when the code that reads them runs as a script (__main__, per PEP 565) and which any -W setting or warning-escalating tool surfaces everywhere else. The migration table below maps each one across.

Migrating to the functional API¶

Each stateful pattern has a direct functional or Network equivalent:

Task	Stateful `Infomap`	Functional / `Network`
Run a graph	`im = Infomap(**opts); im.add_networkx_graph(g); im.run()`	`result = infomap.run(g, **opts)`
Build incrementally	`im.add_node(...)`, `im.add_link(...)`, then `im.run()`	`net = Network(); net.add_node(...); net.add_link(...)`, then `infomap.run(net)`
Reusable configuration	repeat the keyword arguments	`options = Options(**opts)`, then `infomap.run(g, options=options)`
Top-level modules	`im.get_modules()`	`result.modules()`
Iterate `(node_id, module_id)` pairs	`for k, v in im.modules:`	`for k, v in result.modules().items():`
Modules at level k	`im.get_modules(depth_level=k)`	`result.modules(level=k)`
State-node modules	`im.get_modules(states=True)`	`result.modules(states=True)`
Per-node flow	`for n in im.nodes: n.data.flow`	`for n in result.nodes(states=True): n.flow` (`im.nodes` iterates state nodes; plain `result.nodes()` gives physical nodes, identical for first-order networks)
DataFrame	`im.to_dataframe([...])`	`result.to_dataframe([...])`
Scalar metrics	`im.codelength`, `im.num_top_modules`	`result.codelength`, `result.num_top_modules`
Graph-file export	`infomap.io.export.write_graphml(graph, im, path)`	`nx.write_graphml(result.to_networkx(), path)`

The migration has two consistent shifts. You build a network with a Network (or a direct infomap.run() call) rather than on the stateful instance. You read results through the immutable Result (see Reading the result).

Migrating deprecated keyword arguments¶

Advanced engine keywords still work on Infomap() and infomap.run() in 2.x, but they are deprecated and leave those signatures in 3.0. Passing one directly emits a DeprecationWarning, visible by default in __main__ (PEP 565). Each falls into one of three groups, with a recommended replacement:

Deprecated keyword	Where it moves
Advanced tuning options – `regularized`, `core_loop_limit`, `flow_model`, and the like	carry them on the `Options` object: `run(g, options=Options(regularized=True))`
Output-artifact options – `no_file_output`, `tree`, `clu`, `out_name`	write from the `Result` instead: `result.write_tree(path)`, `result.write_clu(path)`, or `network.write_pajek(path)`
Console options – `silent`, `verbosity_level`	use logging: `infomap.enable_log()` for the engine log, and `infomap.enable_log(logging.DEBUG)` to raise its verbosity

The options carrier accepts an Options instance or a plain mapping. It works the same on Infomap(), Infomap.run(), Network.run(), and infomap.run() — for example im.run(options=Options(regularized=True)) gives the stateful builder the same carrier. A bare keyword set to a non-default value overrides it. The common options (seed, num_trials, two_level, directed, markov_time) stay on every signature and are never deprecated.

Removed accessors¶

The redesign dropped a few camelCase passthroughs. Their replacements:

Removed	Use instead
`im.isBipartite()`	set `bipartite_start_id`; there is no separate status accessor
`im.setBipartiteStartId(n)`	`im.bipartite_start_id = n` (a property)
`im.haveMetaData()`	declare with `set_meta_data()`; read `meta_entropy`
`im.numMetaDataDimensions`	Infomap supports one metadata dimension; there is no count accessor