|ci| |docs| |docker|

Infomap
=======

Infomap is a network clustering algorithm based on the `Map equation`_.
This repository contains the native CLI, the Python package, the R package,
the JavaScript web worker, the Docker images, and the source for the
published Python documentation.

Start with `mapequation.org/infomap/`_ for the user guide and
`CHANGELOG.md`_ for release notes.

For contributing, security reporting, and maintainer workflows, see
`CONTRIBUTING.md`_, `SECURITY.md`_, `BUILD.md`_, `ARCHITECTURE.md`_, and
`AGENTS.md`_.

.. |ci| image:: https://github.com/mapequation/infomap/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/mapequation/infomap/actions/workflows/ci.yml
   :alt: CI

.. |docs| image:: https://github.com/mapequation/infomap/actions/workflows/docs.yml/badge.svg
   :target: https://github.com/mapequation/infomap/actions/workflows/docs.yml
   :alt: Docs

.. |docker| image:: https://github.com/mapequation/infomap/actions/workflows/docker-smoke.yml/badge.svg
   :target: https://github.com/mapequation/infomap/actions/workflows/docker-smoke.yml
   :alt: Docker smoke

.. _Map equation: https://www.mapequation.org/publications.html#Rosvall-Axelsson-Bergstrom-2009-Map-equation
.. _`mapequation.org/infomap/`: https://www.mapequation.org/infomap/
.. _`CHANGELOG.md`: https://github.com/mapequation/infomap/blob/master/CHANGELOG.md
.. _`CONTRIBUTING.md`: https://github.com/mapequation/infomap/blob/master/CONTRIBUTING.md
.. _`SECURITY.md`: https://github.com/mapequation/infomap/blob/master/SECURITY.md
.. _`BUILD.md`: https://github.com/mapequation/infomap/blob/master/BUILD.md
.. _`ARCHITECTURE.md`: https://github.com/mapequation/infomap/blob/master/ARCHITECTURE.md
.. _`AGENTS.md`: https://github.com/mapequation/infomap/blob/master/AGENTS.md

Install
-------

Python package
^^^^^^^^^^^^^^

Install from `PyPI`_:

.. code-block:: bash

    pip install infomap

Upgrades use the usual `pip` flow:

.. code-block:: bash

    pip install --upgrade infomap

The package also installs the ``infomap`` CLI entry point.
The Python API reference lives at `Infomap Python API`_.

Quick start with Python:

.. code-block:: python

    from infomap import Infomap, InfomapOptions

    options = InfomapOptions(two_level=True, silent=True, num_trials=20)
    im = Infomap.from_options(options)
    im.add_link(0, 1)
    im.add_link(1, 2)
    im.run()

    print(im.num_top_modules, im.codelength)

.. _PyPI: https://pypi.org/project/infomap/
.. _`Infomap Python API`: https://mapequation.github.io/infomap/python/

R package
^^^^^^^^^

Pre-built binaries are published on `r-universe`_; this is the recommended path:

.. code-block:: r

    install.packages(
      "infomap",
      repos = c("https://mapequation.r-universe.dev", "https://cloud.r-project.org")
    )

Quick start with R:

.. code-block:: r

    library(infomap)

    im <- Infomap(silent = TRUE, two_level = TRUE, num_trials = 20)
    im$add_link(0, 1)
    im$add_link(1, 2)
    im$run()

    print(im$num_top_modules)
    print(im$codelength)

See ``?Infomap`` for the user-facing constructor plus the ``InfomapClass``
method and active-binding reference. The R-specific source README lives at
`interfaces/R/infomap/README.md`_.

.. _r-universe: https://mapequation.r-universe.dev
.. _`interfaces/R/infomap/README.md`: https://github.com/mapequation/infomap/blob/master/interfaces/R/infomap/README.md

Homebrew CLI
^^^^^^^^^^^^

If you want the native CLI without the Python package, install the tap and
formula with:

.. code-block:: bash

    brew tap mapequation/infomap
    brew install infomap

Or install directly in one command:

.. code-block:: bash

    brew install mapequation/infomap/infomap

Upgrade the CLI with the normal Homebrew flow:

.. code-block:: bash

    brew upgrade infomap

JavaScript package
^^^^^^^^^^^^^^^^^^

The browser worker package is published on `NPM`_:

.. code-block:: bash

    npm install @mapequation/infomap

.. _NPM: https://www.npmjs.com/package/@mapequation/infomap

Docker
^^^^^^

Multi-arch images are published to `GHCR`_ for ``linux/amd64`` and
``linux/arm64``:

- ``ghcr.io/mapequation/infomap:latest``
- ``ghcr.io/mapequation/infomap:X.Y.Z``
- ``ghcr.io/mapequation/infomap:notebook``
- ``ghcr.io/mapequation/infomap:notebook-X.Y.Z``

Run the CLI image with:

.. code-block:: bash

    docker run -it --rm \
        -v "$(pwd)":/data \
        ghcr.io/mapequation/infomap:latest \
        [infomap arguments]

Start the notebook image with:

.. code-block:: bash

    docker run \
        -v "$(pwd)":/home/jovyan/work \
        -p 8888:8888 \
        ghcr.io/mapequation/infomap:notebook \
        start.sh jupyter lab

The Dockerfiles in this repository are also smoke-tested in CI and can be
built locally:

.. code-block:: bash

    docker build -f docker/infomap.Dockerfile -t infomap:local .
    docker build -f docker/notebook.Dockerfile -t infomap:notebook-local .

Or use the local Compose file:

.. code-block:: bash

    docker compose run --rm infomap

.. _GHCR: https://github.com/mapequation/infomap/pkgs/container/infomap

Build from source
-----------------

Building locally requires a working ``gcc`` or ``clang`` toolchain.

.. code-block:: bash

    git clone git@github.com:mapequation/infomap.git
    cd infomap
    make build-native

On macOS, the default OpenMP-enabled build may require Homebrew ``libomp``.
If OpenMP is unavailable, use:

.. code-block:: bash

    make build-native OPENMP=0

This creates the ``Infomap`` binary in the repository root.
Show the available CLI options with:

.. code-block:: bash

    ./Infomap --help

See ``BUILD.md`` for platform-specific maintainer build details.

Maintainers should use:

- ``BUILD.md`` for local build and verification commands
- ``RELEASING.md`` for the release flow
- ``ARCHITECTURE.md`` for ownership and source-of-truth rules
- ``AGENTS.md`` for repo-local maintenance guidance
- ``CONTRIBUTING.md`` for pull request and contributor guidance
- ``SECURITY.md`` for vulnerability reporting

Feedback
--------

Usage questions and setup help belong in `GitHub Discussions`_.
Bug reports and feature requests belong in `GitHub issues`_.

.. _`GitHub Discussions`: https://github.com/mapequation/infomap/discussions
.. _`GitHub issues`: https://github.com/mapequation/infomap/issues

Authors
-------

Daniel Edler, Anton Holmgren, Martin Rosvall

For contact information, see `mapequation.org/about.html`_.

.. _`mapequation.org/about.html`: https://www.mapequation.org/about.html

Terms of use
------------

Infomap is released under a dual licence.

The code is available under the GNU General Public License version 3 or any
later version; see `LICENSE_GPLv3.txt`_.
For a non-copyleft license, please contact us.

.. _`LICENSE_GPLv3.txt`: https://github.com/mapequation/infomap/blob/master/LICENSE_GPLv3.txt