Metadata-Version: 2.4
Name: regnets
Version: 0.3.1
Summary: Topology and PyTorch models for self-similar modular neural networks
Author: Ivan Slepovichev
License-Expression: MIT
Project-URL: Repository, https://gitverse.ru/gurgutan/self-similar-nets
Project-URL: Documentation, https://gitverse.ru/gurgutan/self-similar-nets
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: networkx>=3.6.1
Provides-Extra: torch
Requires-Dist: torch>=2.11.0; extra == "torch"
Dynamic: license-file

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

Regnets — библиотека Python для создания топологий и моделей нейронных
сетей в PyTorch. Она предоставляет классы и функции для расчёта,
сохранения JSON и экспорта рисунков SVG или PNG.

[Документация библиотеки](docs/index.md) включает быстрый старт, руководства,
описания программных модулей и справочник API.
На сайте доступны верхние разделы «Документация», «Визуализатор» и «Материалы».
Локальная сборка и просмотр описаны в [руководстве разработчика](docs/contributing.md).

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

## Установка

Требуется Python 3.13 или новее. Пакет доступен на
[PyPI](https://pypi.org/project/regnets/):

```bash
python -m pip install regnets
```

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

```bash
python -m pip install 'regnets[torch]'
```

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

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

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

```python
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`.
Исходный код и подробная документация доступны в
[репозитории проекта](https://gitverse.ru/gurgutan/self-similar-nets).
Лицензия проекта — [MIT](https://gitverse.ru/gurgutan/self-similar-nets/content/master/LICENSE).

## Топология

Теоретические материалы по модульным сетям: [dorogov.su](http://dorogov.su/).

**Основной формат хранения и обмена топологиями — JSON версии 1**:
числовые слова `words`, размерности входов `p` и выходов `g` каждого слоя,
свободное имя и признак двойственности. Полное описание полей, пример и правила
проверки закреплены в [документе дизайна](https://gitverse.ru/gurgutan/self-similar-nets/content/master/DESIGN.md).

```python
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` не указано, выходная
размерность каждого модуля равна его входной размерности.

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

```python
from regnets.topology import Topology

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

Аргументы конструктора, свойства, методы и ограничения описаны
в [справке по топологиям](https://gitverse.ru/gurgutan/self-similar-nets/content/master/docs/topology.md).

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

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

```python
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]`.

```python
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`.
Описание блоков, остаточных связей и сохранения: [вычислительная модель](https://gitverse.ru/gurgutan/self-similar-nets/content/master/docs/modular-nn.md).

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

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

## SVG и PNG из JSON

```python
from regnets.topology.viz import render_topology

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

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

```bash
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](https://gitverse.ru/gurgutan/self-similar-nets/content/master/docs/topology-viz.md).

## Web UI

[Открыть визуализатор на GitVerse Pages](https://gurgutan.gitverse.site/self-similar-nets/).

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

```bash
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](https://gitverse.ru/gurgutan/self-similar-nets/content/master/docs/gitverse-pages.md).

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

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

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

Порядок работы, формат файлов и ограничения описаны в [руководстве визуализатора](https://gitverse.ru/gurgutan/self-similar-nets/content/master/docs/topology-explorer.md).

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

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

```bash
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
```
