Regnets — самоподобные сети

Regnets задаёт топологию модульных нейронных сетей числовыми словами, строит перестановки контактов и вычисляет самоподобные сети в PyTorch. Топологию можно сохранить в JSON и визуализировать в SVG или PNG.

Документация библиотеки включает быстрый старт, руководства, объяснение модели и справочник API, получаемый из исходников при сборке сайта. На сайте доступны верхние разделы «Документация», «Визуализатор» и «Материалы». Локальная сборка и просмотр описаны в руководстве разработчика.

Построение топологий и чтение JSON используют только стандартную библиотеку Python; вычисление выходов выполняет модуль regnets.modular, статическую визуализацию — regnets.topology.viz через Matplotlib. Matplotlib и NetworkX устанавливаются вместе с пакетом; PyTorch подключается отдельно.

Установка

Требуется Python 3.13 или новее. После публикации пакета на PyPI:

python -m pip install regnets

Для вычисления и обучения нейронных сетей установите дополнительную зависимость PyTorch:

python -m pip install 'regnets[torch]'

Без PyTorch доступны топологии, JSON, построение графов и визуализация. Импорт regnets.modular или regnets.kernels без PyTorch завершается ImportError с командой установки. Если установленный PyTorch не может загрузиться, сохраняется исходная ошибка.

Имя установки и корень импортов совпадают: regnets. При необходимости используйте локальное сокращение import regnets as rn; оно не создаёт пакет с именем rn для конструкций from rn....

Быстрый старт

from regnets.topology.lib import cooley_tukey

topology = cooley_tukey((2, 2, 2))
permutations = topology.permutations()
print(len(permutations))  # 4

Основные модули: regnets.topology — построение и сохранение топологий, regnets.modular и regnets.kernels — модели и ядра PyTorch, regnets.topology.viz — визуализация. Прежние импорты topology, modular и kernels заменены соответствующими путями внутри regnets. Исходный код и подробная документация доступны в репозитории проекта. Лицензия проекта — MIT.

Топология

Теоретические материалы по модульным сетям: dorogov.su.

Основной формат хранения и обмена топологиями — JSON версии 1: числовые слова words, размерности входов p и выходов g каждого слоя, свободное имя и признак двойственности. Полное описание полей, пример и правила проверки закреплены в документе дизайна.

from regnets.topology.lib import cooley_tukey, good, haar

p = (2,) * 10  # 1024 входа, десять слоёв
topology = cooley_tukey(p)
permutations = topology.permutations()

good_topology = good(p)
haar_topology = haar(p)
frequency_topology = cooley_tukey(p, decimation="frequency")

Стандартные функции возвращают объект Topology со словами и размерностями модулей. Число слоёв определяется длиной p. Если g не указано, выходная размерность каждого модуля равна его входной размерности.

Топологию можно создать вручную:

from regnets.topology import Topology

topology = Topology(
    [
        [1, 2, 3],
        [-1, 2, 3],
        [-1, -2, 3],
        [-1, -2, -3],
    ],
    p=(2, 2, 2),
)

Положительное число i + 1 обозначает u_i, отрицательное -(i + 1) — v_i. Первый элемент слова соответствует младшему разряду. Для n слоёв задаётся n + 1 слов; выходное поле предыдущего слоя совпадает со входным полем следующего.

Подробные соглашения, примеры индексов и границы поддерживаемых схем описаны в описании модуля топологии.

Сохранение и загрузка топологии

Топологию и размерности модулей можно сохранить в JSON-файл и затем загрузить:

from regnets.topology.io import load_topology, save_topology
from regnets.topology.lib import cooley_tukey

p = (2, 2, 2)
g = (2, 2, 2)
topology = cooley_tukey(p, g=g)
path = save_topology(topology, "topology.json", name="Моя топология")
loaded = load_topology(path)
assert loaded.name == "Моя топология"
assert loaded.topology == topology
assert (loaded.topology.p, loaded.topology.g) == (p, g)
permutations = loaded.topology.permutations()

name — произвольное имя, которое не влияет на связи. save_topology записывает JSON версии 1 в UTF-8, перезаписывает существующий файл и возвращает путь к нему. load_topology проверяет файл и возвращает спецификацию с топологией и её метаданными. Если передать сохранению эту спецификацию, исходные имя и флаг dual сохранятся; необязательный name позволяет заменить имя. При сохранении самого Topology записывается его текущее состояние с dual: false. Файл не содержит весов нейронной сети.

Модель PyTorch

Для этого примера требуется установка regnets[torch].

from regnets.kernels import MLP
from regnets.modular import Layer, ModularNet
from regnets.topology.lib import cooley_tukey

net = ModularNet(
    cooley_tukey((2,) * 8),
    layers=Layer(kernel=MLP(hidden=(64, 32)), shared=False, residual=True, in_size=16),
    device="cpu",
)
# net(x): [..., 256, 16] → [..., 256, 16]

shared=True разделяет параметры между позициями внутри слоя; shared=False хранит независимые параметры упакованными тензорами. Вычисления всех позиций выполняются пакетно. Параметры разных слоёв независимы. Для скалярных контактов пропустите in_size; для разных слоёв передайте список Layer. Описание блоков, остаточных связей и сохранения: вычислительная модель.

Исполняемый пример одного синтетического шага обучения на CPU из клонированного репозитория (после uv sync --extra torch):

CUDA_VISIBLE_DEVICES='' uv run --extra torch python examples/modular_cpu.py

SVG и PNG из JSON

from regnets.topology.viz import render_topology

render_topology("topology.json")  # создаёт topology.svg рядом с JSON
render_topology("topology.json", "network.png", mode="modules")

Отдельная утилита командной строки из клонированного репозитория:

uv run python tools/render_topology.py examples/topology.json -o build/topology.svg
uv run python tools/render_topology.py examples/topology.json -m modules -o build/modules.png

По умолчанию рисуются контакты; -m modules выбирает модули. Формат выбирается расширением .svg или .png, --dpi задаёт разрешение PNG. Web App и экспорт используют одно построение графа; браузер для экспорта не нужен. Подробности: модуль визуализации и CLI.

Web UI

Открыть визуализатор на GitVerse Pages.

Браузерная версия для GitVerse Pages работает без Python-сервера; исходники находятся в apps/topology_pages. Она сохраняет стандартные и ручные топологии, оба представления графа, инспектор, поиск, диапазон слоёв и обмен JSON/PNG.

npm ci
npm test
npm run build
python3 -m http.server 8051 --bind 127.0.0.1 --directory build/pages

Сборка включает фиксированную версию Cytoscape из npm, общий CSS и базовые стили графа из приложения Dash. Обращения к внешнему CDN не нужны. Для сборки нужен Python 3.12+ со стандартной библиотекой; зависимости Dash и PyTorch не устанавливаются. Проверки npm test сравнивают браузерные графы с Python для 112 сочетаний схем, размерностей и диапазонов, включая двойственные модели. Инструкция публикации: GitVerse Pages.

Отдельное приложение на Dash и Dash Cytoscape находится в apps/topology_explorer. Запуск из корня проекта:

uv run --group ui python -m apps.topology_explorer

Откройте http://127.0.0.1:8050. По умолчанию показаны все контакты и связи сети на 16 входов. Кнопки 16, 64 и 256 строят соответствующие сети целиком. Можно выбрать стандартную схему, изменить размерности ядер, задать собственные слова, включить двойственную модель, перейти к контакту по номеру, переключиться на модули, сохранить JSON или рисунок PNG. Настройки каждого сеанса хранятся в его странице браузера.

Порядок работы, формат файлов и ограничения описаны в руководстве визуализатора.

Разработка и проверки

Исходники библиотеки находятся в src/regnets, топологии — в src/regnets/topology. После клонирования репозитория команда uv sync создаёт базовое окружение без PyTorch. Для полного набора тестов и проверки типов выполните uv sync --extra torch --group ui. Проверки выполняются из корня проекта:

uv run --extra torch --group ui python -m pytest -q
uv run --extra torch --group ui python -m ruff check src apps tests tools examples --extend-select I
uv run --extra torch --group ui python -m ruff format --check src apps tests tools examples
uv run --extra torch --group ui python -m pyright src apps tests tools examples