Architecture Decisions

Architecture Decisions#

Last updated: 2026-05-24

This file records accepted technical decisions that should guide future migration work.

ADR-001 Single Private SDK Repository#

MuPRO SDK should converge toward one private engineering repository. The former openmupro split added build and release friction without a realistic code-contribution benefit.

Impact:

  • Common runtime and utility modules live in library/.

  • Future app code may also be folded into the primary SDK repository during app refactors.

  • Public/customer interaction should happen through issues, support, logs, test cases, and requirements rather than direct source contribution.

ADR-002 App Submodules Are Transitional#

The current app submodules remain in place until each app is refactored. Do not spend effort polishing their independent repository workflow unless it is needed for a near-term release.

Impact:

  • apps/muFerro and apps/muPREDICT local cleanup edits are deferred.

  • Future app refactors should decide whether to absorb app code into the SDK repository or keep only release packaging links.

  • App migration should be planned separately from L0/L1 runtime migration.

ADR-003 Desktop Is Out Of Scope#

The old desktop code is not part of the SDK migration. Desktop or GUI products will be redesigned in other software.

Impact:

  • Do not migrate openmupro/desktop.

  • Do not block core SDK migration on GUI build health.

  • Keep SDK examples command-line and library-oriented for now.

ADR-004 Fortran First, C ABI Boundary#

Fortran remains the primary numerical/scientific implementation language. A stable C ABI should be introduced as the long-term cross-language boundary.

Impact:

  • Preserve existing Fortran module APIs during migration.

  • Add C ABI wrappers gradually after runtime ownership and error/status foundations exist.

  • C/C++ code may be used behind the ABI or in backend implementations when justified.

ADR-005 Platform Tiers#

Linux is the Tier 1 high-performance and official release platform. Windows is supported for oneAPI-based workflows when required. macOS is development-only and CPU-only.

Impact:

  • Linux/Windows defaults are oneAPI + oneMKL + MKL FFT.

  • macOS defaults are Homebrew gfortran + OpenBLAS + user-installed FFTW + OpenMPI.

  • macOS should run small examples and smoke checks, not production HPC workloads.

ADR-006 FFTW Is Never Bundled#

FFTW is used only for macOS development builds and must not be bundled into SDK packages.

Impact:

  • macOS developers install FFTW themselves.

  • SDK package scripts should not copy FFTW artifacts.

  • Linux/Windows official builds use MKL FFT.

ADR-007 Reference Code Defines Scientific Baselines#

The old MUPRO snapshot under reference/ is the primary behavior reference for core scientific logic.

Impact:

  • Solver refactors should map current code to reference/Library and reference/Main_Programs/Ferroelectric before changing algorithms.

  • Unconfirmed scientific logic must be marked as 需人确认.

  • Benchmark expected values should trace to reference code or trusted legacy outputs.

Contents