Архитектура#

pyna организована вокруг двух идей:

  1. динамические системы задают правила эволюции на конечномерных фазовых пространствах;

  2. топологические модули описывают геометрические объекты, живущие в этих фазовых пространствах.

Это разделение позволяет одной и той же объектной иерархии представлять тороидальные структуры магнитных силовых линий, гамильтоновы резонансные зоны, классические отображения, орбиты N-тел и стохастические выборочные пути.

Слой 0: динамика#

pyna.topo.dynamics предоставляет абстрактный математический слой:

  • PhaseSpace

  • ContinuousFlow

  • HamiltonianFlow

  • DiscreteMap

  • PoincareMap и GeneralPoincareMap

pyna.dynamics добавляет готовые конечномерные системы:

  • CallableFlow и CallableMap

  • HamiltonianSystem и SeparableHamiltonianSystem

  • NBodySystem

  • ItoSDE, BrownianMotion и GeometricBrownianMotion

Эти классы используют топологическое ядро для выборочных выходов. Детерминированная траектория потока - это pyna.topo.core.Trajectory; дискретное облако итераций - это pyna.topo.core.Orbit.

Слой 1: геометрия#

pyna.topo.core - это domain-agnostic геометрическая иерархия:

Класс

Смысл

Тип времени

Trajectory

конечная выборочная кривая в фазовом пространстве

непрерывное

Cycle

периодическая орбита непрерывного потока

непрерывное

Tube

зона резонанса вокруг эллиптического цикла

непрерывное

TubeChain

семейство tubes с одним резонансом

непрерывное

Orbit

конечные выборочные итерации отображения

дискретное

PeriodicOrbit

конечная периодическая орбита отображения

дискретное

Island

один резонансный остров на сечении

дискретное

IslandChain

периодическая цепочка островов на сечении

дискретное

Ключевой bridge - section_cut:

Cycle       --section_cut--> PeriodicOrbit
Tube        --section_cut--> IslandChain
TubeChain   --section_cut--> IslandChain

Это отражает тороидальный workflow, где непрерывные tubes магнитных островов наблюдаются как дискретные цепочки островов на сечении Пуанкаре.

Слой 2: тороидальная специализация#

pyna.topo.toroidal наследуется от общего ядра:

core.SectionPoint   -> toroidal.FixedPoint
core.PeriodicOrbit  -> toroidal.PeriodicOrbit
core.Cycle          -> toroidal.Cycle
core.Island         -> toroidal.Island
core.IslandChain    -> toroidal.IslandChain
core.Tube           -> toroidal.Tube
core.TubeChain      -> toroidal.TubeChain

Тороидальный слой добавляет:

  • координаты R, Z и phi

  • winding numbers (m, n)

  • DPm и классификацию монодромии

  • cyna-accelerated section cuts и tracing

  • соответствие section-view и helpers реконструкции

Слой 3: workflow и helpers расширения#

pyna.topo.protocols, adapters, builders, bridges и factories предоставляют слой software-engineering расширения. Главная точка входа для notebooks - TopologyWorkflow. Эти helpers держат политику построения и выбор backend вне математических dataclasses: внешние системы могут соответствовать протоколу, нормализовать данные адаптерами, повышать объекты через builders, пересекать непрерывную геометрию через bridges и выбирать runtime-реализации через factories.

Слой 4: ускорение#

cyna реализует узкие места за высокоуровневыми API pyna. Он не должен владеть высокоуровневой научной семантикой объектов; он предоставляет быстрые ядра для tracing, interpolation, fixed-point scans, wall hits и perturbation response.

Правила проектирования#

  • Предпочитайте общие классы pyna.topo.core для новой конечномерной геометрии.

  • Добавляйте тороидально-специфичные поля только в подклассах pyna.topo.toroidal.

  • Выборочная конечная траектория является геометрией, но не автоматически инвариантным множеством.

  • Повышайте объекты до Cycle/PeriodicOrbit только тогда, когда периодическая структура является частью модели или проверена численно.

  • Держите cyna на границах bridges; API прикладного уровня должны возвращать объекты pyna, а не сырые C++-массивы.