Как вносить изменения в ядро¶

Этот раздел — про изменения самого Metatron (ядра). Если вы хотите только использовать проект — новый материал, новое представление, свою физическую процедуру — как правило, ядро трогать не нужно вообще, см. Шаг 7. Расширение без правки ядра. Читайте эту страницу, если планируете менять Core/ напрямую: новый пайплайн, новый солвер, исправление физики, изменение контракта скриптового слоя.

Ветки и коммиты¶

Работа — в отдельной ветке от актуального master, не прямым пушем (см. Ветки и обновление ядра). Имя ветки — по смыслу задачи (refactoring/…, feature/…, конкретная задача).
В master — только состояние, на которое можно безопасно ссылаться из Metatron-Research как submodule: без сломанных смоук-тестов и незавершённых переходных состояний API.
Сообщение коммита — что и зачем изменилось, а не построчный пересказ диффа.

Стиль объектной модели¶

Прежде чем добавлять новый класс, посмотрите на уже существующее разделение и следуйте ему (см. Объектная модель ядра за примерами):

Value-классы (CalculationConfig, GridConfig, LayerSpec) — для всего, что должно допускать независимые копии (в первую очередь — элементы ParameterSeries). Методы, «изменяющие» value-объект, обязаны возвращать новый объект, а не мутировать obj на месте.
Handle-классы — для расчётного состояния и общей изменяемой памяти: Calculation и модельные классы Core/Model, CalculationQueue в скриптовом слое.
Dependent-свойства — для любой величины, однозначно выводимой из других полей (DiffusionCoefficient_SI, MisorientationAngle_Rad, Length_SI): не заводите независимое поле, если оно может рассинхронизироваться с источником при ручном редактировании одного без другого.
Реестры (MaterialRegistry, RepresentationRegistry) — единственная точка добавления нового материала/представления; разработчик ядра добавляет туда запись через Register(...), а не правит код, который перебирает варианты switch/if.

Расширение пайплайна, а не замена¶

Изменения в RunSFIEnergyBasedPipeline/RunSFIMatsubaraPipeline должны оставаться обратно совместимыми со скриптовым слоем: опциональный параметр (как propertyProcedures) — да, изменение сигнатуры существующих обязательных параметров — только с проверкой всех вызывающих мест, включая CalculationRunner.

Документация — часть изменения, не отдельная задача¶

Если изменение затрагивает:

новый публичный класс/метод скриптового слоя — обновите соответствующую страницу Скриптовый слой (Core/Scripting) и, если это новый шаг сценария использования, Как писать скрипты расчёта;
новую физическую процедуру или материал — Шаг 3. Какие величины считать и/или Шаг 7. Расширение без правки ядра;
изменение контракта (сигнатуры, обязательные поля) — проверьте примеры в Metatron-Research/Examples и код в этой документации на актуальность.

Эта справка — статические .rst-страницы (см. Репозитории и установка), не автогенерация по комментариям кода — значит, после изменения кода страницы не обновятся сами.

Проверка перед мержем¶

Формального CI на сегодня нет — проверка вручную, matlab -batch:

Смоук-тест на маленькой сетке: CalculationBuilder.Build собирает конфигурацию без ошибок, CalculationRunner.Run завершает расчёт с props.IsComplete() == true.
Если менялся скриптовый слой — ParameterSeries.Expand + CalculationQueue (Save/Load/RunAll) на 2+ элементах, проверка, что результаты действительно независимы (value-семантика не аляйснула конфиги).
Если менялась физика (солверы, процедуры) — сравнение результата с известным опорным случаем (например, fi=0 — симметричный БКШ-случай без спинового смешивания) на предмет физической разумности, не только отсутствия ошибок выполнения.