diff --git a/assets/diagrams/Core-families.drawio b/assets/diagrams/Core-families.drawio
deleted file mode 100644
index 011a1f0..0000000
--- a/assets/diagrams/Core-families.drawio
+++ /dev/null
@@ -1,95 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/assets/diagrams/Kernel-Components.drawio b/assets/diagrams/Kernel-Components.drawio
deleted file mode 100644
index 355e891..0000000
--- a/assets/diagrams/Kernel-Components.drawio
+++ /dev/null
@@ -1,41 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/assets/diagrams/Kernel-Distributions.drawio b/assets/diagrams/Kernel-Distributions.drawio
deleted file mode 100644
index e54bec2..0000000
--- a/assets/diagrams/Kernel-Distributions.drawio
+++ /dev/null
@@ -1,185 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/assets/diagrams/PySATL-Core-25.12.2025.drawio b/assets/diagrams/PySATL-Core-25.12.2025.drawio
new file mode 100644
index 0000000..ca163e3
--- /dev/null
+++ b/assets/diagrams/PySATL-Core-25.12.2025.drawio
@@ -0,0 +1,1023 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/assets/images/Composition.png b/assets/images/Composition.png
deleted file mode 100644
index 74ac503..0000000
Binary files a/assets/images/Composition.png and /dev/null differ
diff --git a/assets/images/Computation.png b/assets/images/Computation.png
deleted file mode 100644
index 55b2511..0000000
Binary files a/assets/images/Computation.png and /dev/null differ
diff --git a/assets/images/Distrs.png b/assets/images/Distrs.png
deleted file mode 100644
index f48e20a..0000000
Binary files a/assets/images/Distrs.png and /dev/null differ
diff --git a/assets/images/Register.png b/assets/images/Register.png
deleted file mode 100644
index 1a35a1a..0000000
Binary files a/assets/images/Register.png and /dev/null differ
diff --git a/assets/images/components.png b/assets/images/components.png
new file mode 100644
index 0000000..0a4c211
Binary files /dev/null and b/assets/images/components.png differ
diff --git a/assets/images/distributions.computations.png b/assets/images/distributions.computations.png
new file mode 100644
index 0000000..816a379
Binary files /dev/null and b/assets/images/distributions.computations.png differ
diff --git a/assets/images/distributions.distribution-and-strategies.png b/assets/images/distributions.distribution-and-strategies.png
new file mode 100644
index 0000000..636c424
Binary files /dev/null and b/assets/images/distributions.distribution-and-strategies.png differ
diff --git a/assets/images/distributions.registry.png b/assets/images/distributions.registry.png
new file mode 100644
index 0000000..c9ec840
Binary files /dev/null and b/assets/images/distributions.registry.png differ
diff --git a/assets/images/distributions.support.png b/assets/images/distributions.support.png
new file mode 100644
index 0000000..901b699
Binary files /dev/null and b/assets/images/distributions.support.png differ
diff --git a/assets/images/families-class-diagram.png.png b/assets/images/families-class-diagram.png.png
deleted file mode 100644
index b6d6788..0000000
Binary files a/assets/images/families-class-diagram.png.png and /dev/null differ
diff --git a/assets/images/families.png b/assets/images/families.png
new file mode 100644
index 0000000..c64a969
Binary files /dev/null and b/assets/images/families.png differ
diff --git a/assets/images/types.png b/assets/images/types.png
new file mode 100644
index 0000000..8318a60
Binary files /dev/null and b/assets/images/types.png differ
diff --git a/core-design-document.pdf b/core-design-document.pdf
index 93db089..b434028 100644
Binary files a/core-design-document.pdf and b/core-design-document.pdf differ
diff --git a/src/architectural-views/01-context.tex b/src/architectural-views/01-context.tex
index 7491e3a..627091b 100644
--- a/src/architectural-views/01-context.tex
+++ b/src/architectural-views/01-context.tex
@@ -1,3 +1,30 @@
\section{Контекст}
+\label{sec:context}
-\todo[color=green!40, inline]{todo; see \href{https://github.com/PySATL/pysatl-core-design-document/issues/9}{ISSUE}}
+\texttt{PySATL Core} представляет собой вычислительное ядро экосистемы \texttt{PySATL}. Его назначение --- предоставить независимое от конкретных реализаций распределений API для:
+\begin{itemize}[compact]
+ \item создания распределений из параметрических семейств;
+ \item вычисления функциональных и числовых характеристик по единым контрактам;
+ \item генерации выборок с настраиваемой стратегией сэмплирования;
+ \item расширения системы пользователем без модификации исходного кода ядра.
+\end{itemize}
+
+\textbf{Внешние акторы и окружение.}
+Ядро используется конечными пользователями, которым требуется вычислять характеристики и строить выборки, и другими пакетами \texttt{PySATL}, которые строят на базе ядра прикладные методы математической статистики. На уровне инфраструктуры ядро опирается на стандартную среду Python и числовой стек (в первую очередь массивы \texttt{NumPy}); при этом архитектурной целью является уменьшение зависимости прикладных пакетов от \texttt{scipy.stats} за счёт переноса вычислительной модели в собственные модули.
+
+\textbf{Граница системы.}
+В рамках ядра фиксируются контракты распределения, семейств, поддержек (support), стратегий вычислений и сэмплирования, а также глобальный реестр преобразований характеристик. Вне границы системы остаются:
+\begin{itemize}[compact]
+ \item визуализация, статистические тесты и прикладные алгоритмы верхнего уровня;
+ \item конкретные численные методы интегрирования/оптимизации, если они предоставляются внешними библиотеками;
+ \item хранение данных и пользовательские интерфейсы прикладных пакетов.
+\end{itemize}
+
+\textbf{Точки расширения.}
+Архитектура предполагает, что пользователи и пакеты экосистемы могут:
+\begin{itemize}[compact]
+ \item регистрировать новые семейства и параметризации;
+ \item добавлять новые аналитические реализации характеристик;
+ \item добавлять новые вычислительные методы и правила вывода в глобальный реестр характеристик;
+ \item подменять стратегии вычислений и сэмплирования для конкретного распределения.
+\end{itemize}
diff --git a/src/architectural-views/02-composition.tex b/src/architectural-views/02-composition.tex
index 61b0459..85e60a4 100644
--- a/src/architectural-views/02-composition.tex
+++ b/src/architectural-views/02-composition.tex
@@ -1,56 +1,61 @@
\section{Композиция}
-
\label{sec:composition}
-Ядро строится вокруг трёх компонент: \textit{Distributions}, \textit{Families} и \textit{Transformations}.
-Они объединены общей идеей: все вычисления характеристик случайных величин происходят по единым контрактам, а сами компоненты остаются слабо связаны и расширяемы.
-
-\subsection{Роли компонент}
-
-\paragraph{Families.}
-Families отвечает за параметризацию и рождение конкретных распределений.
-Под параметризацией понимается множество имён параметров, а под параметрами --- отображение этих имён в значения.
-Поддерживается несколько параметризаций для одной и той же семьи, однако все вычисления выполняются через базовую параметризацию.
-Перед любыми вычислениями параметры приводятся к базовой форме, чтобы остальные компоненты работали с единым представлением.
-Families сохраняет смысловую целостность параметров, их допустимость и область определения будущего распределения.
-
-\paragraph{Distributions.}
-Distributions --- единая поверхность доступа к характеристикам распределений и точка их композиции.
-Компонента материализует распределение, зная его семью и параметры, и предоставляет согласованный интерфейс к характеристикам: функциям распределения, плотности, квантилям, моментам и т.\,д.
-Distributions не решает, \emph{как} именно получена та или иная характеристика; она лишь координирует вычисление по зависимостям и контрактам, в том числе для составных объектов, которые появились в результате преобразований.
-
-\paragraph{Transformations.}
-Transformations фиксирует операции над распределениями и правила пересчёта характеристик после этих операций.
-Сюда попадают преобразования вида «аффинное», «сдвиг и масштаб», «сумма/микс», «свёртка», «обрезка (truncation)», «монотонные отображения» и другие композиции.
-Компонента описывает, \emph{какие} характеристики нового распределения можно выразить через характеристики исходных и в каком порядке они должны вычисляться.
-На момент написания модуль проектно важен, но ещё не реализован; он задаёт общий язык описания преобразований и обеспечивает единообразную логику пересчёта поддержек, моментов, квантилей и прочих характеристик при переходе к результату преобразования.
+Архитектура \texttt{PySATL Core} организована вокруг набора относительно независимых компонент, объединённых общей вычислительной моделью: характеристики распределения вычисляются через единые контракты, а правила вывода оформляются как расширяемый граф зависимостей. Такая композиция позволяет наращивать систему (новыми семействами, характеристиками, способами вычислений и сэмплирования) без модификации уже реализованных частей.
-\subsection{Поток данных и точки соприкосновения}
+\subsection{Состав компонент}
-Рабочий цикл выглядит просто. Пользователь выбирает семью и задаёт параметры в удобной для него параметризации.
-Families приводит параметры к базовой форме и передаёт контекст в Distributions.
-Когда требуется характеристика, Distributions строит локальный граф зависимостей для этого запроса.
-Если характеристика получена применением преобразования, узлы этого графа добавляются модулем Transformations, а рёбра указывают, какие характеристики исходных распределений нужны для пересчёта.
-Таким образом, вычисления идут от стандартизованных параметров через согласованные правила преобразований к запрошенной характеристике результата.
+На уровне верхней декомпозиции выделяются следующие компоненты (рис.~\ref{fig:components}):
+\begin{itemize}[compact]
+ \item \textbf{\texttt{families}} --- описание параметрических семейств распределений, их параметризаций и ограничений, а также фабрика построения конкретных распределений;
+ \item \textbf{\texttt{distributions}} --- единая «поверхность» доступа к распределению: вычисление характеристик, выбор стратегий, работа с поддержкой (support) и интеграция с реестром характеристик;
+ \item \textbf{\texttt{sampling}} --- инфраструктура генерации выборок и представления результата (тип выборки), поставляемая как отдельная, переиспользуемая часть ядра;
+ \item \textbf{\texttt{transformations}} --- компонент описания преобразований распределений и правил пересчёта характеристик при композиции (на момент актуализации проектно значим и рассматривается как целевое расширение).
+\end{itemize}
-\subsection{Границы и контракты}
-
-Межкомпонентное взаимодействие опирается на несколько устойчивых сущностей:
-базовая параметризация, область значения случайной величины (support), именованный реестр характеристик и спецификация преобразований.
-Компоненты не разделяют внутреннее состояние и обмениваются только тем, что необходимо для вычисления.
-Это позволяет добавлять новые семьи и новые преобразования без изменения существующих модулей, сохраняя обратную совместимость.
-
-\subsection{Композиционные свойства}
-
-Композиция прозрачна: результат преобразования ведёт себя как обычное распределение, подчиняясь тем же контрактам Distributions.
-Порядок вычисления характеристик незначим для внешнего пользователя, так как зависимости и правила вывода зашиты в Transformations.
-Единая базовая параметризация в Families гарантирует сопоставимость результатов при смешении разных источников и представлений параметров.
+Внутри компонентов выделены подсистемы, фиксирующие устойчивые точки расширения:
+\begin{itemize}[compact]
+ \item в \texttt{distributions} --- \texttt{registry}, содержащий глобальный реестр преобразований характеристик и механизмы получения \emph{локального} представления графа для конкретного распределения;
+ \item в \texttt{families} --- \texttt{builtins}, включающий готовые семейства и общие элементы описания параметризаций.
+\end{itemize}
\begin{figure}[H]
\centering
- % Замените путь на ваш файл со схемой компонентов.
- % Если у вас PDF/PNG, оставьте только одно расширение
- \includegraphics[width=.85\linewidth]{assets/images/Composition.png}
- \caption{Компоненты ядра и их роли в композиции}
- \label{fig:kernel-components}
-\end{figure}
\ No newline at end of file
+ \includegraphics[width=.65\linewidth]{components.png}
+ \caption{Компоненты ядра и границы публичных API}
+ \label{fig:components}
+\end{figure}
+
+\subsection{Роли компонент}
+
+\paragraph{\texttt{families}.}
+Компонент отвечает за \emph{порождение} распределений. Семейство задаётся как объект, содержащий набор параметризаций и правила их приведения к базовой форме. Для каждой параметризации могут быть объявлены ограничения на параметры. Результатом работы \texttt{families} является объект распределения, который реализует контракт \texttt{Distribution} и тем самым бесшовно подключается к вычислительной модели \texttt{distributions}.
+
+\paragraph{\texttt{distributions}.}
+Компонент определяет контракт распределения и обеспечивает вычисление характеристик. В частности, он фиксирует:
+\begin{itemize}[compact]
+ \item \emph{идентификаторы характеристик} (на уровне типов) и единый механизм запроса вычисления;
+ \item \emph{стратегии} вычислений и сэмплирования как взаимозаменяемые политики;
+ \item \emph{поддержку} случайной величины как отдельный объект со своими инвариантами;
+ \item \emph{реестр характеристик} как расширяемый ориентированный граф правил вывода.
+\end{itemize}
+Компонент не фиксирует конкретный численный алгоритм «внутри» каждого метода, но задаёт формат его подключения и условия применимости.
+
+\paragraph{\texttt{sampling}.}
+Компонент инкапсулирует генерацию выборок и представление результата. Конкретные алгоритмы сэмплирования поставляются через \texttt{SamplingStrategy}; при этом распределение хранит выбранную стратегию как часть своего состояния и делегирует ей операцию \texttt{sample}.
+
+\paragraph{\texttt{transformations}.}
+Компонент предназначен для описания преобразований распределений (например, аффинные преобразования, смеси, свёртки) и их влияния на характеристики и поддержку. В целевой архитектуре такие правила должны быть выражены через те же абстракции вычислительных методов, что и «внутренние» преобразования характеристик, и регистрироваться в общем графе. Это обеспечивает единый путь вычисления характеристик как для атомарных распределений, так и для составных.
+
+\subsection{Потоки данных и точки соприкосновения}
+
+Типовой поток использования выглядит следующим образом:
+\begin{enumerate}[compact]
+ \item Пользователь выбирает семейство и задаёт параметры в удобной параметризации.
+ \item \texttt{families} валидирует параметры и приводит их к базовой параметризации.
+ \item Создаётся объект распределения, предоставляющий \texttt{Distribution}-API.
+ \item При запросе характеристики \texttt{distributions} выбирает подходящий метод: либо из аналитически заданных вычислений, либо через вывод по графу реестра; при необходимости применяется кэширование.
+ \item При запросе выборки распределение делегирует генерацию выборки стратегии \texttt{SamplingStrategy}.
+\end{enumerate}
+
+Таким образом, граница между компонентами проводится по \emph{контрактам}: \texttt{families} формирует корректный экземпляр распределения, а \texttt{distributions} обеспечивает вычислительную инфраструктуру и расширяемость через реестр и стратегии.
diff --git a/src/architectural-views/03-logical-structure.tex b/src/architectural-views/03-logical-structure.tex
index 3b46f50..1fbe5c8 100644
--- a/src/architectural-views/03-logical-structure.tex
+++ b/src/architectural-views/03-logical-structure.tex
@@ -1,6 +1,8 @@
\section{Логическая структура}
+\label{sec:logical-structure}
+
\input{src/architectural-views/logical-structure/01-overview}
-%\newpage
+\newpage
\input{src/architectural-views/logical-structure/02-distributions}
\newpage
\input{src/architectural-views/logical-structure/03-parametric-families}
diff --git a/src/architectural-views/04-interaction.tex b/src/architectural-views/04-interaction.tex
index 625f8db..db42bfe 100644
--- a/src/architectural-views/04-interaction.tex
+++ b/src/architectural-views/04-interaction.tex
@@ -1,85 +1,57 @@
-\section{Взаимодействие}
-
\section{Взаимодействия и потоки выполнения}
\label{sec:interactions}
-В этом разделе фиксируются ключевые сценарии взаимодействия компонентов вычислительной модели:
-поиск и вычисление характеристик, генерация выборки, политика кэширования и точки расширения.
+В этом разделе фиксируются ключевые сценарии выполнения в вычислительной модели: поиск и применение метода вычисления характеристики, генерация выборки, а также точки расширения (регистрация новых правил и подмена стратегий).
\subsection{Поток вычисления характеристики}
-Запрос целевой характеристики (см. UML на рис.~\ref{fig:uml-computation}) обрабатывается стратегией
-\texttt{ComputationStrategy} по следующему алгоритму:
-\begin{enumerate}
- \item \textbf{Аналитика.} Проверяется наличие \emph{аналитической} реализации \texttt{AnalyticalComputation}
- для требуемого \texttt{target} в экземпляре \texttt{Distribution}.
- \item \textbf{Кэш.} При включённом кэшировании выполняется lookup по ключу, зависящему от:
- (i) идентичности распределения, (ii) имени характеристики, (iii) входных данных и
- (iv) переданных \texttt{**options}. При попадании результат возвращается немедленно.
- \item \textbf{Маршрут.} Если ни аналитики, ни кэша нет, стратегия запрашивает в
- \texttt{DistributionTypeRegister} (рис.~\ref{fig:uml-register}) маршрут
- \texttt{find\_path(source, target)} в графе характеристик для типа данного распределения.
- \item \textbf{Пошаговое вычисление.} По рёбрам маршрута последовательно применяются назначенные
- \texttt{ComputationMethod}-ы. Если для пары узлов определено несколько методов, стратегия может
- выбрать конкретную реализацию на основании \texttt{**options} или внутренних эвристик.
- \item \textbf{Мемоизация.} Итоговое значение сохраняется в кэш согласно политике стратегии и возвращается
- вызывающей стороне.
+Запрос характеристики начинается с обращения к объекту распределения через \texttt{query\_method} или \texttt{calculate\_characteristic}. Дальнейшее поведение делегируется стратегии вычислений:\begin{enumerate}[compact]
+ \item \textbf{Аналитический якорь.} Если в \texttt{analytical\_computations} присутствует реализация для целевой характеристики, стратегия возвращает \texttt{AnalyticalComputation}.
+ \item \textbf{Кэш подогнанных методов.} При включённом кэшировании выполняется поиск уже построенного \texttt{FittedComputationMethod} для данной характеристики (и, при необходимости, набора \texttt{**options}). Если метод найден, он возвращается немедленно.
+ \item \textbf{Построение по реестру.} Если аналитической реализации нет, стратегия запрашивает у глобального \texttt{CharacteristicRegistry} локальный вид графа: \texttt{view = registry.view(distr)}. В \texttt{RegistryView} выполняется поиск пути от доступных якорей (как правило, от характеристик, присутствующих в \texttt{analytical\_computations}) к целевой характеристике. Поиск пути (\texttt{find\_path}) выполняется с учётом:
+ \begin{itemize}[compact]
+ \item наличия узлов и рёбер в локальном виде графа;
+ \item ограничений применимости (constraints), зависящих от признаков типа распределения и/или параметров экземпляра;
+ \item предпочтений по метке варианта (\texttt{prefer\_label}) и глобального порядка \texttt{label\_preference}.
+ \end{itemize}
+ \item \textbf{Подгонка и композиция.} Для каждого шага найденного пути выбирается конкретный вариант перехода (\texttt{EdgeMeta}), после чего соответствующий \texttt{ComputationMethod} подгоняется под распределение через \texttt{fit(distr, **options)}. Полученная последовательность \texttt{FittedComputationMethod} компонуется в единый вызываемый объект для целевой характеристики.
+ \item \textbf{Мемоизация.} Итоговый подогнанный метод сохраняется в кэш стратегии и возвращается вызывающей стороне.
\end{enumerate}
-Инварианты реестра гарантируют существование маршрутов между \emph{definitive}-узлами
-и отсутствие обратных рёбер из \emph{indefinitive} в \emph{definitive}, что упрощает выбор валидных путей.
+После получения метода \texttt{calculate\_characteristic} применяет его к входному аргументу (например, к точке $x$ для \texttt{pdf}/\texttt{cdf} или к массиву $p$ для \texttt{ppf}).
\subsection{Опции вычислений (\texorpdfstring{\texttt{**options}}{**options})}
-И \texttt{GenericCharacteristic}, и \texttt{ComputationMethod} принимают дополнительные параметры,
-влияющие на вычисление. Пример: инверсия \texttt{cdf}\,$\to$\,\texttt{ppf} с выбором ветви
-\texttt{most\_left}/\texttt{most\_right}. Стратегия \emph{может} проигнорировать часть опций,
-но пользователь вправе подключить свою \texttt{ComputationStrategy}/\texttt{ComputationMethod},
-которые их учитывают. Для предсказуемости результат должен рассматриваться как функция пары
-(входные данные, опции).
+Параметр \texttt{**options} используется как сквозной канал настройки вычислений и может влиять на:
+\begin{itemize}[compact]
+ \item выбор варианта перехода в реестре (например, предпочтение численного/аналитического метода);
+ \item поведение подгонки (\texttt{fit}) и подготовку внутренних структур;
+ \item поведение вызова подогнанного метода (например, точность, ограничения итераций и т.п.).
+\end{itemize}
+
+Архитектурно \texttt{**options} трактуется как часть контекста вычисления: при наличии кэширования рекомендуется включать его (или его нормализованное представление) в ключ кэша.
\subsection{Поток генерации выборки}
-Генерация выборки делегируется \texttt{SamplingStrategy}:
-\begin{enumerate}
- \item вызывается \texttt{sampling\_strategy.sample(n, distr, **options)};
- \item стратегия по умолчанию генерирует \texttt{n} равномерных вероятностей и применяет к ним \texttt{ppf}
- данного распределения (см. рис.~\ref{fig:uml-distributions});
- \item результат помещается в \texttt{ArraySample} (\texttt{NumPy}-совместная обёртка).
+Генерация выборки делегируется стратегии сэмплирования:\begin{enumerate}[compact]
+ \item вызывается \texttt{distr.sample(n, **options)};
+ \item внутри \texttt{sample} выполняется \texttt{sampling\_strategy.sample(n, distr, **options)};
+ \item результат возвращается в виде объекта, реализующего протокол \texttt{Sample} (обычно \texttt{ArraySample}).
\end{enumerate}
-Стратегию можно переопределить для имитационного моделирования или специализированных процедур
-(например, стратифицированная или квазислучайная выборка).
-
-\subsection{Кэширование: политика и ключи}
-Кэширование реализовано внутри \texttt{DefaultComputationStrategy} и прозрачно для клиента.
-Рекомендуется формировать ключ кэша как хеш неизменяемого представления
-\{тип и параметры распределения, целевая характеристика, входные данные, опции, выбранный маршрут/метод\}.
-Такой ключ обеспечивает корректность при наличии альтернативных методов между теми же узлами.
-Иммутабельность экземпляров распределений упрощает инвалидацию: глобальная очистка выполняется только
-при смене стратегии или конфигурации.
-
-\subsection{Точки расширения и совместимость}
-
-Архитектура поддерживает расширение без модификации существующих интерфейсов:
-\begin{itemize}
- \item \textbf{Стратегии.} Замена \texttt{SamplingStrategy} и/или \texttt{ComputationStrategy}
- позволяет настроить маршрутизацию, кэш и интерпретацию \texttt{**options}.
- \item \textbf{Методы.} Добавление новых \texttt{ComputationMethod}/\texttt{FittedComputationMethod}
- вводит альтернативные рёбра графа. Во избежание конфликтов не рекомендуется использовать
- зарезервированное имя \texttt{DEFAULT\_COMPUTATION\_KEY}.
- \item \textbf{Аналитические якоря.} Расширение набора \texttt{AnalyticalComputation} для конкретного
- распределения упрощает и ускоряет вычисления, сокращая длину маршрутов.
- \item \textbf{Реестр.} Операции \texttt{register\_definitive}, \texttt{add\_bidirectional\_conversion},
- \texttt{add\_conversion} позволяют безопасно наращивать граф с сохранением инвариантов.
+Такое разделение позволяет:
+\begin{itemize}[compact]
+ \item подключать специальные алгоритмы сэмплирования для отдельных распределений;
+ \item переиспользовать представление выборки и последующую обработку в прикладных пакетах;
+ \item тестировать стратегии независимо от конкретных семейств.
\end{itemize}
-\subsection{Ошибки и диагностика}
+\subsection{Точки расширения}
-При нарушении инвариантов реестра (например, попытка зарегистрировать второй исходный definitive-узел в
-пустом графе) выбрасывается исключение конфигурации. Для диагностики полезны:
-\begin{enumerate}
- \item трассировка выбранного маршрута (последовательность узлов и имён методов);
- \item отметка источника результата (аналитика/кэш/маршрут);
- \item контроль версий для пользовательских методов, добавленных в реестр.
-\end{enumerate}
+Архитектура допускает расширение без модификации существующих интерфейсов:
+\begin{itemize}[compact]
+ \item \textbf{Новые правила вывода.} Пользователь может добавить в \texttt{CharacteristicRegistry} новую характеристику или новое правило перехода (\texttt{add\_characteristic}, \texttt{add\_computation}), снабдив его ограничениями применимости.
+ \item \textbf{Новые семейства и параметризации.} Через \texttt{ParametricFamilyRegister} (см.~рис.~\ref{fig:uml-families}) регистрируются новые семейства; в рамках семейства добавляются параметризации и ограничения.
+ \item \textbf{Подмена стратегий.} Для распределения можно заменить \texttt{ComputationStrategy}/\texttt{SamplingStrategy}, что меняет политику выбора методов, кэширование и способ генерации выборки.
+ \item \textbf{Варианты методов.} Для одной пары характеристик могут сосуществовать альтернативные реализации, различающиеся меткой и условиями применимости; стратегия выбирает вариант, используя предпочтения и \texttt{**options}.
+\end{itemize}
diff --git a/src/architectural-views/logical-structure/01-overview.tex b/src/architectural-views/logical-structure/01-overview.tex
index 69d46b4..ace0708 100644
--- a/src/architectural-views/logical-structure/01-overview.tex
+++ b/src/architectural-views/logical-structure/01-overview.tex
@@ -1 +1,19 @@
-\subsection{Общий обзор}
\ No newline at end of file
+\subsection{Общий обзор}
+\label{subsec:logical-overview}
+
+Логическая структура ядра строится вокруг небольшого набора устойчивых типов и контрактов, которые используются во всех компонентах:
+\begin{itemize}[compact]
+ \item \textbf{протоколы} (\texttt{typing.Protocol}) задают интерфейсы \texttt{Distribution}, стратегий и вычислительных процедур, позволяя реализовывать их без жёсткой иерархии наследования;
+ \item \textbf{типизированные идентификаторы} (например, \texttt{GenericCharacteristicName}, \texttt{FamilyName}) унифицируют адресацию характеристик и семейств;
+ \item \textbf{тип распределения} (\texttt{DistributionType}) и связанные с ним признаки (\texttt{registry\_features}) предоставляют входные данные для ограничений применимости правил вывода характеристик;
+ \item \textbf{носитель} (\texttt{Support}) описывает множество допустимых значений случайной величины и используется как в семействе (для вывода support из параметров), так и в вычислениях (для выбора корректных правил).
+\end{itemize}
+
+На рис.~\ref{fig:types} приведён обзор ключевых общесистемных типов. Указанные сущности выступают «языком сопряжения» между \texttt{families}, \texttt{distributions} и будущими \texttt{transformations}: правила и стратегии опираются на них, но не зависят от конкретных реализаций распределений.
+
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=.7\linewidth]{types.png}
+ \caption{Общие типы и идентификаторы: виды распределений, имена характеристик и семейств, а также базовые представления носителя}
+ \label{fig:types}
+\end{figure}
diff --git a/src/architectural-views/logical-structure/02-distributions.tex b/src/architectural-views/logical-structure/02-distributions.tex
index 28b2bfd..ea1ecaa 100644
--- a/src/architectural-views/logical-structure/02-distributions.tex
+++ b/src/architectural-views/logical-structure/02-distributions.tex
@@ -1,119 +1,96 @@
-\subsection{Модуль Distributions}
-В основе лежит класс \texttt{Distribution}, представленный в виде протокола Python. Это означает, что конкретные классы могут \emph{реализовать} интерфейс \texttt{Distribution}, не наследуясь от общего базового класса. По этой причине почти все поля \texttt{Distribution} экспонируются как свойства (\texttt{@property}); обзор ключевых элементов модуля показан на рис.~\ref{fig:uml-distributions}.
+\subsection{Модуль \texttt{distributions}}
+\label{subsec:distributions-module}
-\begin{figure}[h]
- \centering
- \includegraphics[width=.66\linewidth,trim=4mm 4mm 4mm 4mm,clip]{assets/images/Distrs.png}
- \caption{UML-обзор модуля \texttt{Distributions}: протокол \texttt{Distribution},
- типы \texttt{DistributionType}, стратегии \texttt{SamplingStrategy}/\texttt{ComputationStrategy},
- выборки и базовые реализации по умолчанию.}
- \label{fig:uml-distributions}
-\end{figure}
-
-\subsubsection{Тип распределения (\texttt{DistributionType})}
+Компонент \texttt{distributions} задаёт единый контракт распределения и инфраструктуру вычислений. Ключевое проектное решение состоит в том, что пользовательский объект распределения предоставляет лишь минимальный набор свойств и методов, а выбор конкретных алгоритмов делегируется стратегиям и глобальному реестру характеристик. Такая схема отделяет описание распределения от правил вывода и обеспечивает расширяемость.
-\texttt{DistributionType} — маркерный тип, задающий родовую принадлежность распределения и цепочку наследований признаков, которые принципиально различают семейства распределений. Пример: \texttt{EuclidianDistributionType} со свойствами \texttt{kind} (\texttt{Discrete}/\texttt{Continuous}) и размерностью (евклидово пространство фиксированной размерности). Этот тип не содержит логики вычислений, но определяет область применимости правил преобразований характеристик.
+\subsubsection{Контракт \texttt{Distribution} и стратегии}
-\subsubsection{Стратегии: выборки и вычислений}
+На рис.~\ref{fig:uml-distribution-and-strategies} показан интерфейс \texttt{Distribution} в виде протокола Python. Использование протокола позволяет реализовывать распределения как в составе ядра, так и в стороннем коде без принудительного наследования от общего базового класса.
-\textbf{Стратегия сэмплирования (\texttt{SamplingStrategy}).}
-Свойство \texttt{sampling\_strategy} определяет алгоритм генерации выборки из распределения. Стратегия по умолчанию использует квантили (\texttt{ppf}) в сочетании с равномерным распределением для генерации входных вероятностей.
-
-\textbf{Стратегия вычислений (\texttt{ComputationStrategy}).}
-Свойство \texttt{computation\_strategy} задаёт политику получения функциональных характеристик. Стратегия принимает решения: выдавать ли характеристику из аналитически заданных, читать её из кэша, либо строить через цепочку преобразований. В реализации по умолчанию применяется следующий порядок:
-\begin{enumerate}
- \item проверка наличия аналитической реализации целевой характеристики;
- \item проверка кэша результатов;
- \item поиск пути на графе реестра преобразований (см.~\S\ref{subsec:registry}) и пошаговое вычисление.
-\end{enumerate}
-Базовая стратегия поддерживает кэширование; кэш прозрачен для вызывающей стороны.
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=.85\linewidth]{distributions.distribution-and-strategies.png}
+ \caption{\texttt{Distribution} и связанные стратегии вычислений и сэмплирования, а также представление выборки}
+ \label{fig:uml-distribution-and-strategies}
+\end{figure}
-\subsubsection{Аналитические характеристики (\texttt{AnalyticalComputation})}
+Интерфейс \texttt{Distribution} фиксирует:
+\begin{itemize}[compact]
+ \item \texttt{distribution\_type}: тип распределения (см.~рис.~\ref{fig:types}), используемый для задания признаков и ограничения применимости правил;
+ \item \texttt{support}: объект носителя (support), описывающий допустимые значения случайной величины;
+ \item \texttt{analytical\_computations}: словарь аналитически заданных вычислений характеристик, выступающих «якорями» для вывода остальных;
+ \item \texttt{sampling\_strategy} и \texttt{computation\_strategy}: взаимозаменяемые политики генерации выборки и выбора метода вычисления.
+\end{itemize}
-\texttt{AnalyticalComputation} — это набор функциональных характеристик, заданных в явном (аналитическом) виде и не требующих вывода через другие характеристики. Для каждого конкретного распределения должен существовать хотя бы один такой «якорь», обеспечивающий возможность построения остальных характеристик через реестр преобразований. Здесь \emph{не} подразумевается внешняя «база данных»; речь идёт о \emph{базисе} характеристик самого распределения.
+Вычисления инициируются через два метода:
+\begin{itemize}[compact]
+ \item \texttt{query\_method(...)} возвращает вызываемый объект (метод вычисления) для указанной характеристики;
+ \item \texttt{calculate\_characteristic(...)} выполняет вычисление немедленно, применяя найденный метод к переданному аргументу.
+\end{itemize}
+Такое разделение удобно для переиспользования: один и тот же метод может быть запрошен один раз и затем применён к набору входных значений.
-\subsubsection{Выборки и правдоподобие}
+\paragraph{Стратегия вычислений.}
+\texttt{ComputationStrategy} отвечает за выбор конкретного способа получения характеристики. Реализация по умолчанию (\texttt{DefaultComputationStrategy}) решает две задачи: выбирает, можно ли вернуть аналитическую реализацию напрямую, и, при необходимости, строит вычисление через граф преобразований характеристик, дополняя это кэшированием результатов «подгонки» методов (fitting).
-\texttt{Sample} и \texttt{ArraySample} — лёгкие обёртки над массивами \texttt{NumPy}, хранящие выборку и метаданные. Для любой реализации \texttt{Distribution} возможно:
-\begin{itemize}
- \item сгенерировать выборку согласно \texttt{sampling\_strategy};
- \item вычислить (лог-)\,функцию правдоподобия для этой выборки.
-\end{itemize}
+\paragraph{Стратегия сэмплирования.}
+\texttt{SamplingStrategy} инкапсулирует алгоритм генерации выборки и возвращает объект, реализующий протокол \texttt{Sample}. Базовая реализация \texttt{DefaultSamplingStrategy} задаёт безопасный путь по умолчанию, а специализированные стратегии могут учитывать особенности распределения, генератора случайных чисел или требования к качеству сэмплирования.
-\subsubsection{Протокол вычисления характеристики (\texttt{Computation})}
+\subsubsection{Вычислительная модель характеристик}
-\texttt{Computation} — абстракция вычислительной процедуры для конкретной характеристики (структура на рис.~\ref{fig:uml-computation}):
-\begin{itemize}
- \item \texttt{target} — идентификатор целевой характеристики;
- \item \texttt{\_\_call\_\_} — унифицированный вызов вычисления.
+Единая модель вычислений показана на рис.~\ref{fig:uml-computations}. В ядре различаются:
+\begin{itemize}[compact]
+ \item \textbf{\texttt{Computation}} --- минимальный контракт вычисления конкретной характеристики (\texttt{target}) как вызываемого объекта;
+ \item \textbf{\texttt{AnalyticalComputation}} --- прямое (аналитическое) вычисление, не требующее предварительной подготовки;
+ \item \textbf{\texttt{ComputationMethod}} --- «шаблон» вычисления, который сначала \emph{подгоняется} под конкретное распределение (\texttt{fit}), а затем превращается в \textbf{\texttt{FittedComputationMethod}} --- вызываемый объект, пригодный для многократного применения.
\end{itemize}
-\texttt{AnalyticalComputation} реализует \texttt{Computation}. Расширение протокола — \texttt{FittedComputationMethod}: оно вводит понятие \emph{источников} (\emph{sources}) — набора характеристик, из которых получается новая. Конкретная реализация \texttt{FittedComputationMethod} заполняет все поля и предоставляет функцию \texttt{func}, задающую фактическое преобразование.
-Отдельно выделяется \texttt{ComputationMethod} — абстракция для сложных вычислений, которые не укладываются в сигнатуру вызова \texttt{FittedComputationMethod}. В частности, \texttt{ComputationMethod} намеренно \emph{не} определяет \texttt{fit} как \texttt{\_\_call\_\_}, поскольку его сигнатура отличается. Такое разделение упрощает кэширование и повторное использование результатов.
-
-\begin{figure}[h]
+\begin{figure}[H]
\centering
- \includegraphics[width=.66\linewidth,trim=4mm 4mm 4mm 4mm,clip]{assets/images/Computation.png}
- \caption{Вычислительная модель: \texttt{Computation}, \texttt{AnalyticalComputation},
- \texttt{FittedComputationMethod} и \texttt{ComputationMethod}; целевая характеристика (\texttt{target}),
- источники (\texttt{sources}) и единый механизм вызова.}
- \label{fig:uml-computation}
+ \includegraphics[width=.78\linewidth]{distributions.computations.png}
+ \caption{Абстракции вычислений характеристик: аналитические вычисления, методы и подогнанные методы}
+ \label{fig:uml-computations}
\end{figure}
-\subsubsection{Имена характеристик и единый механизм вызова}
+Ключевое различие между \texttt{ComputationMethod} и \texttt{FittedComputationMethod} состоит в том, что «подгонка» позволяет захватить параметры распределения, выбранные численные настройки и подготовленные структуры данных (например, сетки или табличные аппроксимации). Это делает кэширование эффективным: стратегия может хранить уже подогнанные методы и не выполнять подготовку повторно.
-\texttt{GenericCharacteristicName} — типизированное имя характеристики (не протокол). Вызов для любой характеристики унифицирован:
-\begin{enumerate}
- \item у стратегии, закреплённой за распределением, запрашивается подходящий метод для \texttt{target};
- \item полученный метод вызывается над переданными данными.
-\end{enumerate}
+Поле \texttt{sources} фиксирует зависимости: вычисление целевой характеристики (\texttt{target}) может требовать значений других характеристик. Эти зависимости используются стратегией вычислений при построении цепочки вывода по графу реестра.
-\textbf{Опции вычислений (\texttt{\textbf{**options}}).}
-И \texttt{Characteristic}, и \texttt{ComputationMethod} поддерживают дополнительные параметры, влияющие на ход вычислений. Пример: при восстановлении \texttt{ppf} по \texttt{cdf} можно задать стратегию выбора ветви \texttt{most\_left}/\texttt{most\_right}. Конкретная стратегия \emph{может} проигнорировать опцию, однако пользователь волен подключить собственную стратегию, которая эти опции учитывает.
+\subsubsection{Носитель (support)}
-\subsubsection{Реестр преобразований характеристик}
-\label{subsec:registry}
+Носитель случайной величины оформлена как самостоятельный объект. Это позволяет валидировать значения, выражать свойства области определения в правилах вывода, и унифицировать обработку непрерывных и дискретных случаев. На рис.~\ref{fig:uml-support} показана структура интерфейсов носителей.
-Сердцем архитектуры является \texttt{DistributionTypeRegister} — синглтон, содержащий для каждого \texttt{DistributionType} ориентированный граф переходов между характеристиками (см. рис.~\ref{fig:uml-register}).
+\begin{figure}[H]
+ \centering
+ \includegraphics[width=.75\linewidth]{distributions.support.png}
+ \caption{Модель носителя: \texttt{Support}, \texttt{DiscreteSupport} и базовые реализации}
+ \label{fig:uml-support}
+\end{figure}
-\textbf{Структура графа.}
-\begin{itemize}
- \item Узлы — имена характеристик.
- \item Рёбра — помечены парами \{имя, \texttt{ComputationMethod}\}. Имя по умолчанию зарезервировано как
- \[
- \texttt{DEFAULT\_COMPUTATION\_KEY} \equiv \texttt{"PySATL\_default\_computation"}.
- \]
- Зарезервированное имя используется для поставляемых реализаций по умолчанию и не рекомендуется для пользовательских методов, чтобы избежать непреднамеренного переопределения.
-\end{itemize}
+Для непрерывного одномерного случая используется интервальное представление (\texttt{Interval1D}), из которого наследуется \texttt{ContinuousSupport}. Для дискретного случая предусмотрены две базовые реализации: \texttt{ExplicitTableDiscreteSupport} (конечное множество точек) и \texttt{IntegerLatticeDiscreteSupport} (целочисленная решётка). Наличие итераторов по точкам и ближайшим значениям позволяет строить численные процедуры, зависящие от структуры support.
-\textbf{Классификация узлов.}
-Все характеристики делятся на:
-\begin{itemize}
- \item \emph{definitive} — однозначно задающие распределение (например, \texttt{pdf}, \texttt{cdf}, \texttt{ppf});
- \item \emph{indefinitive} — вычислимые по известным характеристикам, но не задающие распределение однозначно (например, математическое ожидание, дисперсия, медиана).
-\end{itemize}
+\subsubsection{Глобальный реестр характеристик}
+\label{subsec:characteristic-registry}
-\textbf{Инварианты.}
-\begin{enumerate}
- \item Подграф \emph{definitive}-узлов всегда связен: из любой definitive-характеристики существует путь в любую другую.
- \item \emph{Indefinitive}-узлы являются стоками: обратных рёбер из них в множество definitive нет.
-\end{enumerate}
-
-\textbf{Операции реестра.}
-Предоставляются следующие методы управления графом:
-\begin{itemize}
- \item \texttt{register\_definitive(name)} — регистрация \emph{единственного} начального definitive-узла в пустом графе. Если попытаться добавить второй исходный узел, сработает проверка инвариантов и будет брошено исключение.
- \item \texttt{add\_bidirectional\_conversion(a, b, method\_ab, method\_ba)} — либо добавляет пару взаимосвязанных узлов в пустой граф, либо присоединяет новый узел к уже существующему связному компоненту (рёбра в обе стороны обязательны, иначе нарушится связность definitive-подграфа).
- \item \texttt{add\_conversion(a, b, method, name?)} — добавляет альтернативный маршрут между уже соединёнными узлами; тем самым поддерживаются множественные реализации преобразования.
- \item Служебные запросы: \texttt{is\_definitive(name)}, \texttt{definitive\_nodes()}, \texttt{indefinitive\_nodes()}, \texttt{all\_nodes()}.
- \item Поиск маршрута: \texttt{find\_path(source, target)} — стандартный \texttt{BFS} по графу, используемый стратегией по умолчанию и доступный пользователю при реализации собственных стратегий.
+Центральным механизмом расширения является глобальный синглтон \texttt{CharacteristicRegistry} (рис.~\ref{fig:uml-registry}). Реестр хранит:
+\begin{itemize}[compact]
+ \item множество известных характеристик и их классификацию на \emph{definitive}/\emph{indefinitive};
+ \item ориентированный граф переходов между характеристиками;
+ \item набор вариантов (label-ов) для одного и того же перехода, позволяющий иметь несколько реализаций;
+ \item ограничения применимости правил (constraints), зависящие от признаков типа распределения и/или экземпляра.
\end{itemize}
-\begin{figure}[h]
+\begin{figure}[H]
\centering
- \includegraphics[width=.5\linewidth,trim=4mm 4mm 4mm 4mm,clip]{assets/images/Register.png}
- \caption{Реестр преобразований для типа распределения: \texttt{DistributionTypeRegister}
- и \texttt{GenericCharacteristicRegister} с инвариантами (связность definitive-подграфа,
- отсутствие обратных рёбер из indefinitive).}
- \label{fig:uml-register}
-\end{figure}
\ No newline at end of file
+ \includegraphics[width=.8\linewidth]{distributions.registry.png}
+ \caption{Реестр характеристик: ограничения применимости, метаданные рёбер, глобальный \texttt{CharacteristicRegistry} и локальный \texttt{RegistryView}}
+ \label{fig:uml-registry}
+\end{figure}
+
+\paragraph{Ограничения применимости.}
+Ограничение задаётся как предикат \texttt{allows(...)} и может проверять как свойства распределения, так и произвольные дополнительные признаки, поставляемые через \texttt{DistributionType.registry\_features}. Составное ограничение \texttt{GraphPrimitiveConstraint} позволяет выражать правила вида «данная характеристика/переход присутствует только при выполнении условий на тип распределения и параметры экземпляра».
+
+\paragraph{Локальный вид графа.}
+Метод \texttt{CharacteristicRegistry.view(distr)} строит \texttt{RegistryView} --- представление графа, отфильтрованное под конкретное распределение. В \texttt{RegistryView} доступны операции навигации (\texttt{successors}/\texttt{predecessors}), перечисление вариантов перехода между двумя узлами и поиск пути \texttt{find\_path}. Именно \texttt{RegistryView} используется стратегией вычислений, что позволяет отделить глобальную конфигурацию реестра от конкретного контекста выполнения.
+
+\paragraph{Варианты переходов и предпочтения.}
+Переход между одной и той же парой характеристик может иметь несколько вариантов, различающихся метками (\texttt{label}) и/или ограничениями. Поле \texttt{label\_preference} в реестре задаёт порядок предпочтения, а стратегия вычислений может дополнительно выбирать вариант на основании \texttt{**options}.
diff --git a/src/architectural-views/logical-structure/03-parametric-families.tex b/src/architectural-views/logical-structure/03-parametric-families.tex
index e3d55a0..0e68686 100644
--- a/src/architectural-views/logical-structure/03-parametric-families.tex
+++ b/src/architectural-views/logical-structure/03-parametric-families.tex
@@ -1,160 +1,55 @@
\subsection{Модуль \texttt{families}}
-Модуль \texttt{families} предоставляет фреймворк для работы с параметрическими семействами распределений в Python. Система позволяет определять семейства распределений с множественными параметризациями, ограничениями на параметры и методами вычисления характеристик распределений.
+\label{subsec:families-module}
-\subsubsection{Общий обзор}
+Компонент \texttt{families} обеспечивает описание параметрических семейств распределений и построение конкретных экземпляров распределений из параметров. В отличие от \texttt{distributions}, который фиксирует «как вычислять», модуль \texttt{families} фиксирует «что такое распределение данного семейства»: набор параметров, допустимость значений, носитель и базовые (аналитические) характеристики.
-На \picref{fig:class-diagram-families} представлена UML-диаграмма классов модуля \texttt{families}
-
-\begin{figure}[h]
+\begin{figure}[H]
\centering
- \includegraphics[width=\figurewidth]{assets/images/families-class-diagram.png}
- \caption{Диаграмма классов модуля families}
- \label{fig:class-diagram-families}
+ \includegraphics[width=.9\linewidth]{families.png}
+ \caption{Ключевые классы модуля \texttt{families}: семейство, параметризации, распределение и реестр семейств}
+ \label{fig:uml-families}
\end{figure}
-Реестр семейств, используется, чтобы в будущем можно было реализовывать переходы между распределениями из семейств, при каких-то операциях
+\subsubsection{Семейство распределений: \texttt{ParametricFamily}}
-Каждое семейство является объектом класса \texttt{ParametricFamily}. Это позволяет использовать систему с реестром, а также:
+\texttt{ParametricFamily} представляет одно семейство распределений и хранит:
\begin{itemize}[compact]
- \item Добавлять пользовательские параметризации для распределений;
- \item Добавлять новые \texttt{AnalyticalComputation} для распределений,
-\end{itemize}
-не модифицируя исходный код семейства.
-
-На данный момент за работу с несколькими параметризациями отвечает класс \texttt{ParametrizationSpec}. Его объекты описывают какие параметризации есть у семейства, и кто из них является канонической. Сейчас используется следующий механизм: все аналитические вычисления задаются в базовой параметризации, далее каждая параметризация указывает, как из нее получить базовую параметризацию.
-
-\subsubsection{Основные компоненты системы}
-
-\noindent \texttt{ParametricFamiliesRegister} (Реестр параметрических семейств)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Синглтон-класс для глобальной регистрации и доступа ко всем параметрическим семействам.\item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{\_instance} - единственный экземпляр реестра
- \item \texttt{\_registered\_families} - словарь зарегистрированных семейств
- \end{itemize}
- \item \textbf{Методы}:
- \begin{itemize}[compact]
- \item \texttt{get(name)} - получение семейства по имени
- \item \texttt{register(family)} - регистрация нового семейства
- \end{itemize}
-\end{itemize}
-
-\noindent \texttt{ParametrizationConstraint} (Ограничение параметризации)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Контейнер для ограничений на значения параметров распределения.
-
- \item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{description} - текстовое описание ограничения
- \item \texttt{check} - функция проверки ограничения
- \end{itemize}
-\end{itemize}
-
-\noindent \texttt{Parametrization} (Абстрактный класс параметризации)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Абстрактный базовый класс для всех параметризаций распределений.
-
- \item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{constraints} - список ограничений параметров
- \end{itemize}
-
- \item \textbf{Абстрактные свойства}:
- \begin{itemize}[compact]
- \item \texttt{name} - имя параметризации
- \item \texttt{parameters} - словарь параметров
- \end{itemize}
-
- \item \textbf{Методы}:
- \begin{itemize}[compact]
- \item \texttt{validate()} - проверка всех ограничений
- \item \texttt{transform\_to\_base\_parametrization()} - преобразование к базовой параметризации.
- \end{itemize}
+ \item набор доступных параметризаций и имя базовой параметризации;
+ \item правила приведения параметров к базовой форме;
+ \item аналитические реализации характеристик, привязанные к параметризациям;
+ \item \texttt{support\_resolver} --- функцию/объект, выводящий носитель распределения по параметрам.
\end{itemize}
-\noindent \texttt{ParametrizationSpec} (Спецификация параметризаций)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Контейнер для управления множественными параметризациями семейства.
-
- \item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{parametrizations} - словарь всех параметризаций
- \item \texttt{base\_parametrization\_name} - имя базовой параметризации
- \end{itemize}
-
- \item \textbf{Методы}:
- \begin{itemize}[compact]
- \item \texttt{base} - получение класса базовой параметризации
- \item \texttt{add\_parametrization()} - добавление новой параметризации
- \item \texttt{get\_base\_parameters()} - преобразование параметров к базовой форме
- \end{itemize}
-\end{itemize}
+Семейство предоставляет фабричный метод \texttt{distribution(...)}. Он принимает значения параметров (и, опционально, имя параметризации), валидирует их и возвращает объект \texttt{ParametricFamilyDistribution}, реализующий протокол \texttt{Distribution}. Таким образом, дальнейшие вычисления выполняются уже в инфраструктуре \texttt{distributions}.
+\subsubsection{Параметризации и ограничения}
-\noindent \texttt{ParametricFamily} (Параметрическое семейство)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Представление семейства распределений с различными параметризациями.
-
- \item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{name} - имя семейства
- \item \texttt{distr\_type} - тип распределения
- \item \texttt{parametrizations} - спецификация параметризаций
- \item \texttt{distr\_characteristics} - характеристики распределения
- \item \texttt{sampling\_strategy} - стратегия семплирования
- \item \texttt{computation\_strategy} - стратегия вычислений
- \end{itemize}
-
- \item \textbf{Методы}:
- \begin{itemize}[compact]
- \item \texttt{\_\_call\_\_()} - создание экземпляра распределения
- \end{itemize}
+Параметризация представлена классом \texttt{Parametrization}. Экземпляр параметризации содержит словарь значений параметров и предоставляет:
+\begin{itemize}[compact]
+ \item \texttt{validate()} --- проверку набора ограничений;
+ \item \texttt{transform\_to\_base\_parametrization()} --- преобразование параметров к базовой параметризации семейства.
\end{itemize}
+Ограничения оформляются объектами \texttt{ParametrizationConstraint} (описание + предикат \texttt{check}). Важное свойство такой схемы состоит в том, что ограничения задаются рядом с параметризацией и остаются локальными: добавление новой параметризации не требует модификации существующих.
-\noindent \texttt{ParametricFamilyDistribution} (Конкретное распределение)
-\begin{itemize}[noitemsep, topsep=0pt, parsep=0pt]
- \item \textbf{Назначение}: Конкретный экземпляр распределения с определенными параметрами. Реализует протокол \texttt{Distribution}
+\subsubsection{Аналитические характеристики и план вывода}
- \item \textbf{Поля}:
- \begin{itemize}[compact]
- \item \texttt{distr\_name} - имя семейства
- \item \texttt{distribution\_type} - тип распределения
- \item \texttt{parameters} - параметры распределения
- \end{itemize}
+Семейство хранит набор аналитических реализаций характеристик (на уровне \texttt{GenericCharacteristicName}) и допускает, что разные характеристики удобнее задавать в разных параметризациях. Для этого используется \texttt{analytical\_plan}: он задаёт, к какой параметризации следует привести параметры, чтобы использовать доступную аналитическую формулу.
- \item \textbf{Свойства}:
- \begin{itemize}[compact]
- \item \texttt{family} - ссылка на родительское семейство
- \end{itemize}
-\end{itemize}
+На уровне экземпляра распределения (\texttt{ParametricFamilyDistribution}) формируется отображение \texttt{analytical\_computations}. Эти вычисления становятся «якорями» для дальнейшего вывода характеристик по реестру (см.~\S\ref{subsec:characteristic-registry}).
-\subsubsection{Типичные сценарии использования}
+\subsubsection{Экземпляр распределения: \texttt{ParametricFamilyDistribution}}
-\paragraph{Определение нового семейства распределений}
-Пользователь создает новое параметрическое семейство, определяя:
+\texttt{ParametricFamilyDistribution} связывает воедино:
\begin{itemize}[compact]
- \item Различные параметризации (каноническая, mean-var, etc.)
- \item Ограничения на параметры
- \item Функции для вычисления характеристик (PDF, CDF, etc.), доступные аналитически
- \item Стратегии семплирования и вычислений
+ \item семейство и выбранную параметризацию;
+ \item конкретные значения параметров (в том числе в базовой форме);
+ \item \texttt{support} и \texttt{distribution\_type};
+ \item стратегии вычислений и сэмплирования.
\end{itemize}
-\paragraph{Создание экземпляра распределения}
-Пользователь создает конкретное распределение, указывая:
-\begin{itemize}[compact]
- \item Имя семейства
- \item Параметризацию (как минимум одну)
- \item Значения параметров
-\end{itemize}
+Такое распределение является полноценным объектом \texttt{Distribution}: оно может генерировать выборку через \texttt{sampling\_strategy} и вычислять характеристики через \texttt{computation\_strategy}.
-\paragraph{Вычисление характеристик распределения}
-Система автоматически:
-\begin{itemize}[compact]
- \item Проверяет корректность параметров
- \item При необходимости преобразует к базовой параметризации
- \item Вычисляет запрошенные характеристики
-\end{itemize}
+\subsubsection{Глобальный реестр семейств}
-\paragraph{Генерация выборок}
-Используется зарегистрированная стратегия семплирования для генерации данных из распределения.
+Для поддержки готовых семейств и интеграции с другими пакетами экосистемы введён синглтон \texttt{ParametricFamilyRegister}. Он предоставляет операции регистрации семейства, получения по имени и перечисления зарегистрированных семейств. Наличие отдельного реестра позволяет подключать «поставки» семейств из разных модулей, не связывая их напрямую.
diff --git a/src/chapter-05.tex b/src/chapter-05.tex
index bf6c051..6e8d346 100644
--- a/src/chapter-05.tex
+++ b/src/chapter-05.tex
@@ -1,6 +1,7 @@
\chapter{Избранные архитектурные точки зрения}
\input{src/architectural-views/01-context}
-\input{src/architectural-views/02-composition.tex}
+\input{src/architectural-views/02-composition}
\input{src/architectural-views/03-logical-structure}
-% \input{src/architectural-views/04-interaction}
+\newpage
+\input{src/architectural-views/04-interaction}