Рабочие процессы динамики и средства расширения#

pyna отделяет математическую геометрию от политики построения.

Основная иерархия остается компактной:

  • геометрия непрерывного времени: Trajectory, Cycle, Tube, TubeChain;

  • геометрия дискретного времени: Orbit, PeriodicOrbit, Island, IslandChain;

  • тороидальные классы остаются публичными топологическими специализациями по умолчанию под pyna.topo.Tube, pyna.topo.Cycle и pyna.topo.IslandChain.

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

Фасад рабочего процесса#

TopologyWorkflow - рекомендуемая первая точка входа для учебников и скриптов анализа. Он компонует низкоуровневые вспомогательные средства в путь, которым реально следуют пользователи:

  1. построить или получить поток/отображение;

  2. интегрировать Trajectory или итерировать Orbit;

  3. явно повысить замкнутые выборки до Cycle или PeriodicOrbit;

  4. пересечь объекты Cycle/Tube/TubeChain сечением.

Фасад намеренно тонкий. Он не вводит новой математики; он делает код ноутбука читаемым и при этом сохраняет каждое повышение явным.

Проработанный учебник#

Для компактного обзора рабочего процесса начните с Мини-кейсы. Для полного визуального учебника, применяющего те же идеи повышения к реальному тороидальному расчету, используйте Анализ резонансов RMP в аналитическом стеллараторе. Он показывает выборочные пересечения Пуанкаре, явную геометрию X/O-неподвижных точек, наложения координатных сеток и локальные ветви многообразий.

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

Протоколы#

pyna.topo.protocols определяет структурные контракты, такие как FlowLike, MapLike, SectionLike и TubeLike. Используйте их при добавлении нового предметного пакета, который должен взаимодействовать с pyna без прямого наследования от каждого базового класса.

Адаптеры#

pyna.topo.adapters преобразует пользовательские данные в стабильные объекты ядра:

  • массивы или выводы решателей в Trajectory и Orbit;

  • точки или fixed-point-like объекты в SectionPoint;

  • проверенные выборки в PeriodicOrbit или Cycle по запросу.

Адаптеры нормализуют представление; они не должны скрывать математические утверждения. Например, открытая выборочная траектория остается Trajectory, если вызывающий код явно не просит Cycle и не принимает или не передает проверку замкнутости.

Построители#

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

Мосты#

CoreSectionCutBridge - стандартный мост от непрерывного времени к дискретному для объектов ядра:

  • Cycle.section_cut(section) возвращает PeriodicOrbit;

  • Tube.section_cut(section) возвращает IslandChain;

  • TubeChain.section_cut(section) объединяет получившиеся острова.

Тороидальные объекты уже владеют оптимизированными методами section_cut. Используйте их напрямую или вызовите TopologyWorkflow.section_cut(...) и позвольте объекту выбрать собственную реализацию.

Фабрики#

DynamicalSystemFactory строит готовые системы из стабильных строковых ключей, таких как callable-flow, callable-map, hamiltonian, nbody и geometric-brownian-motion.

PoincareMapFactory выбирает исполняемую реализацию отображения возврата. Значение backend="auto" по умолчанию сейчас выбирает переносимый GeneralPoincareMap, если не переданы аргументы кэша поля cyna.

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

Правила совместимости#

  • Не меняйте pyna.topo.Tube, Cycle или IslandChain так, чтобы они указывали на классы ядра; используйте CoreTube, CoreCycle и CoreIslandChain для общих корней.

  • Не используйте поддельные сечения с утиной типизацией на тороидально-специфичных границах. Используйте полноценные объекты Section.

  • Рассматривайте реестры как изменяемое состояние. Используйте локальные экземпляры Registry в тестах и зависимых пакетах, когда важна изоляция.