Модули топологии

regnets.topology предоставляет класс Topology, а regnets.topology.lib — функции создания стандартных топологий. Эти модули доступны при базовой установке пакета и не требуют PyTorch.

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

Модуль	Назначение
`regnets.topology`	Класс `Topology` и типы `Word`, `Permutation`
`regnets.topology.lib`	Функции `cooley_tukey`, `good`, `haar`
`regnets.topology.io`	Чтение, проверка и сохранение JSON
`regnets.topology.graph`	Данные графа для визуализации
`regnets.topology.viz`	Экспорт SVG и PNG

Примеры использования #

Генераторы топологий #

Каждая функция возвращает готовый Topology. Параметр p содержит положительное целое число входов модуля для каждого слоя. Параметр g задаёт число выходов в том же формате; при его отсутствии используется p.

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

topology = cooley_tukey((2, 2, 2))
frequency = cooley_tukey((2, 2, 2), decimation="frequency")
good_topology = good((2, 2, 2))
haar_topology = haar((2, 2, 2))

assert topology.n_layers == 3
assert topology.sizes == (8, 8, 8, 8)

У cooley_tukey параметр decimation принимает "time" или "frequency". Все три функции принимают g=... и dual=True. Сигнатуры и параметры перечислены в справочнике генераторов.

Создание Topology #

Конструктор принимает words, p, необязательный g и именованный флаг dual. Списки копируются в неизменяемые кортежи.

from regnets.topology import Topology

topology = Topology(
    [[1, 2], [-1, 2], [-1, -2]],
    p=(2, 2),
)
assert topology.n_layers == 2
assert topology.p == topology.g == (2, 2)

words — последовательность списков целочисленных кодов. Размеры списков и допустимые значения описаны в контракте JSON; конструктор проверяет те же ограничения. Для стандартной топологии используйте готовый генератор.

Нулевые и нецелые коды, повторения, неправильный состав списков, неположительные или несовместимые размерности вызывают ValueError. Логические значения не принимаются вместо целых чисел.

Свойства и методы #

Обращение	Результат
`topology.words`	Неизменяемые кортежи кодов
`topology.p`, `topology.g`	Числа входов и выходов модуля по слоям
`topology.n_layers`	Число слоёв
`topology.sizes`	Число контактов на входе, между слоями и на выходе
`topology.n_modules(m)`	Число модулей слоя с индексом `m`
`topology.dual()`	Новый объект двойственной топологии
`topology.permutations()`	Кортежи целочисленных индексов для вычислений

Индексы слоёв начинаются с нуля. n_modules(m) вызывает ValueError, если индекс не является целым числом или выходит за пределы слоёв.

topology = cooley_tukey((2, 3), g=(2, 2))
assert topology.sizes == (6, 6, 4)
assert topology.n_modules(0) == 3
assert topology.n_modules(1) == 2

Метод dual #

dual() возвращает новый Topology, преобразуя words, p и g. Исходный объект сохраняется. Повторный вызов восстанавливает исходную топологию:

topology = good((2, 3), g=(3, 2))
dual_topology = topology.dual()
assert dual_topology.dual() == topology

Для создания такого объекта сразу используйте dual=True в конструкторе или генераторе. Описание математической двойственности находится в теории.

Метод permutations #

permutations() возвращает topology.n_layers + 1 кортежей неотрицательных целых индексов в порядке применения: перед первым слоем, между слоями и после последнего слоя.

Каждый кортеж указывает, из какой позиции исходного массива взять очередной элемент результата:

topology = cooley_tukey((2, 2))
indices = topology.permutations()[1]
source = [10, 11, 20, 21]
result = [source[index] for index in indices]
assert result == [10, 20, 11, 21]

Кортежи можно преобразовать в индексы выбранной вычислительной библиотеки. При использовании ModularNet это выполняется автоматически.

Чтение и сохранение #

from regnets.topology.io import load_topology, save_topology

path = save_topology(topology, "topology.json", name="Пример")
spec = load_topology(path)
assert spec.topology == topology
assert spec.name == "Пример"

load_topology возвращает TopologySpec; объект Topology доступен в поле spec.topology. save_topology перезаписывает файл назначения. Параметры, возвращаемые значения и ошибки описаны в справочнике ввода и вывода.

Ограничения интерфейса #

Topology хранит описание последовательных слоёв; произвольный граф ветвлений и объединений этим классом не задаётся. Веса, вычислительные ядра, устройство и состояние обучения задаются в regnets.modular и regnets.kernels.

Полные сигнатуры класса и методов: справочник Topology.

Формат JSON v1 #

JSON версии 1 — основной формат хранения и обмена полным описанием топологии проекта. Полное описание включает числовые слова и размерности входов/выходов нейронных модулей каждого слоя. По этим данным восстанавливаются топология, число контактов и все перестановки для вычислений.

Файл имеет расширение .json, кодировку UTF-8 и содержит один объект:

{
  "version": 1,
  "name": "Моя топология",
  "p": [2, 3],
  "g": [3, 1],
  "words": [
    [1, 2],
    [2, -1],
    [-2, -1]
  ],
  "dual": false
}

Поле	Смысл и правила
`version`	Целое число `1`, версия формата
`name`	Произвольная строка с названием топологии; может быть пустой
`p`	Массив n положительных целых чисел; `p[m]` — число входных контактов каждого модуля слоя m
`g`	Массив n положительных целых чисел; `g[m]` — число выходных контактов каждого модуля слоя m
`words`	Массив n+1 списков длины n с целочисленными кодами топологии
`dual`	Логическое значение; `true` выбирает двойственную топологию

В канонической записи присутствуют все шесть полей. p и g всегда записываются полностью, по одному значению на слой, даже если значения одинаковы или p == g. Порядок полей объекта и форматирование несущественны; порядок элементов массивов существенен. Число слоёв выводится как n = len(words) - 1 и отдельно не записывается.

Пример описывает два слоя с ядрами 2 → 3 и 3 → 1: на входе сети 6 контактов, после первого слоя — 9, на выходе — 3. Числа контактов доступны через Topology.sizes, число модулей слоя — через Topology.n_modules(m).

Коды. В списке с индексом m должны присутствовать отрицательные коды от -m до -1 и положительные от m+1 до n, каждый ровно один раз. Индексы списков начинаются с нуля. Коды — целые числа; нули, повторы, неправильные знаки, строки, дробные и логические значения вместо целых недопустимы. Для стандартных схем готовые данные создают функции regnets.topology.lib.

Название. name — произвольная подпись, которая не определяет связи и не проверяется на соответствие стандартному генератору. Связи задаются только словами и размерностями. Интерфейс может построить слова по стандартной схеме, но при чтении файла использует записанные слова независимо от имени. При отсутствии name используется строковое поле scheme из прежних файлов, а при отсутствии обоих — пустая строка. Если присутствуют оба поля, приоритет имеет name. Сохранение всегда записывает только name. Прежние версии программы прочитают слова и размерности нового файла, но не распознают name и не сохранят его при повторной записи.

Двойственность. При dual: true поля words, p, g описывают исходную топологию. После чтения один раз выполняется Topology.dual(): преобразуются words, p и g. Полученный объект используется в вычислениях и визуализации. При сохранении записываются исходные данные и флаг dual. Для совместимости с ранними файлами отсутствующее dual читается как false. Записывающий код всегда выводит name и dual явно.

Производные представления. Кортежи Python, список числовых слов в TXT и тензоры индексов — рабочие представления. TXT хранит только слова и сам по себе не задаёт полную топологию: размерности p/g в нём отсутствуют. Массивы перестановок вычисляются из JSON и не дублируются в основном файле. Конфигурация нейронного ядра, size, режим разделения параметров, остаточные связи и обученные веса относятся к вычислительной модели и хранятся отдельно.

Проверяются версия, тип имени и флага двойственности, типы и длины массивов, положительность размерностей и состав слов. Ограничения Web UI на число слоёв, размерности и размер загружаемого файла — ограничения приложения, а не формата JSON. Несовместимое изменение смысла полей требует новой версии формата. Примеры работы с классом и методами приведены в документации топологии. Математические основы описаны в теории модульных сетей.

Общая проверка и чтение формата выполняются в regnets.topology.io: load_topology(path) возвращает TopologySpec с выбранным Topology (слова и размерности), именем и исходным флагом двойственности; parse_topology(data) проверяет уже прочитанный объект JSON. save_topology(topology, path, name=...) записывает JSON версии 1 в UTF-8; при передаче TopologySpec сохраняются её имя и исходный флаг двойственности, а для Topology записывается текущее состояние с dual: false. Ограничения Web UI применяются отдельно в приложении. Экспорт SVG/PNG использует тот же формат; интерфейс описан в руководстве визуализации.

regnets.topology #

Справочник публичного API Regnets 0.3.1. Сигнатуры, поля и описания получены из исходников при сборке. Имена в <factory: …> обозначают фабрики значений dataclass.

Класс Topology и типы Word, Permutation. Примеры использования.

Имя	Тип	По умолчанию
`words`	`tuple[Word, ...]`	Обязательно
`p`	`tuple[int, ...]`	Обязательно
`g`	`tuple[int, ...]`	Обязательно

Имя	Тип	По умолчанию
`name`	`str`	Обязательно
`topology`	`Topology`	Обязательно
`dual`	`bool`	`False`

Имя	Тип	По умолчанию
`inputs`	`tuple[tuple[int, ...], ...]`	Обязательно
`outputs`	`tuple[tuple[int, ...], ...]`	Обязательно
`module_word`	`tuple[int, ...]`	Обязательно
`module_radices`	`tuple[int, ...]`	Обязательно

Модули топологии

Примеры использования #

Генераторы топологий #

Создание Topology #

Свойства и методы #

Метод dual #

Метод permutations #

Чтение и сохранение #

Ограничения интерфейса #

Формат JSON v1 #

regnets.topology #

Word #

Permutation #

Topology #

Поля #

Topology.dual #

Topology.n_layers #

Topology.sizes #

Topology.n_modules #

Topology.permutations #

regnets.topology.lib #

cooley_tukey #

good #

haar #

regnets.topology.io #

TopologySpec #

Поля #

TopologySpec.to_dict #

parse_topology #

load_topology #

save_topology #

regnets.topology.graph #

field_label #

symbol #

digits #

radices #

Layer #

Поля #

layer_contacts #

estimate_elements #

module_port #

build_graph #

regnets.topology.viz #

render_topology #