Skip to content

Port the URAMSES, CODEGEN and compile toolchain to Python #2

Description

@apetros

Why

Writing your own device model is the one capability the Python edition does not
have. stepss bundles RAMSES and Helios; CODEGEN is carried by STEPSS GUI, and
that asymmetry is documented across the site as a plain limitation: "CODEGEN is
the one capability it lacks."

The consequence for a user is worse than the sentence sounds. Everything else in
a study can be scripted, but the moment it needs a custom exciter, governor,
injector or two-port, the workflow leaves Python entirely: install the desktop
application, use its Codegen tab or CODEGEN Studio, compile there, then come back.
For a parameter sweep over a model the user wrote themselves, which is a very
common research task, there is no scripted path at all.

What "the toolchain" means here

Three pieces, and they are separable, which matters for sequencing:

  1. CODEGEN: translate a model description into Fortran 2003. A binary, so this
    is a wrapping and packaging job rather than a reimplementation.
  2. A Fortran compile step: build the generated .f90 and link it against the
    pre-compiled RAMSES library. Needs gfortran, GNU make and OpenBLAS on the
    user's machine, which the site already documents as the custom-model toolchain.
  3. URAMSES: the existing mechanism for exactly this, linking user models
    against a pre-compiled RAMSES library. It already builds a shared library for
    the Python edition
    as well as a standalone executable, and it is Apache 2.0,
    so the hard part may already be done and this becomes a matter of driving it
    from Python rather than by hand.

Suggest starting at (3) and checking how much of (2) URAMSES already covers, since
that decides whether this is a wrapper or a build system.

Constraints worth deciding early

  • CODEGEN is not redistributable in the way this package is. It is the
    property of Dr. Thierry Van Cutsem, distributed as a compiled executable under
    an Academic Public License, with no public source. This package is Apache 2.0,
    so bundling it makes the wheel mixed-licence and needs the rights holder's
    agreement first. The same question is open for CODEGEN Studio in
    Bundle the codegen executables stepss-cg-studio#2 and the two should be answered together rather than
    separately.
  • A compiler on the user's machine is a real prerequisite, unlike everything
    else pip install stepss needs. Decide whether a missing gfortran is a hard
    error at call time with a clear message, or whether model building is an extras
    install that states the requirement up front.
  • Three platforms, and Windows needs MSYS2 for the toolchain, which is the
    least pleasant part of the current documented path and will not get better by
    being scripted.
  • The custom simulator is a build artefact with a lifetime. The GUI keeps one
    per session and lets you save it. Python needs an explicit answer: where the
    built library lives, when it is rebuilt, and how a script pins one so a sweep
    does not silently change simulator halfway through.

Docs

developer/user-models.md owns the model language and developer/uramses.md the
linking mechanism. getting-started/overview.md currently states the limitation
this issue removes, in the "Two Editions" comparison, and
getting-started/quickstart.md has a CODEGEN column that is empty for Python.
Those are the places to update when it lands.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions