Skip to content
STEPSS

URAMSES

URAMSES provides the framework and tools needed to compile and link custom Fortran models with stepss and the STEPSS GUI.

This is the route for user models. RAMSES resolves a model name against the models compiled into it, so your own models are linked into the engine and reach it the same way the built-in ones do. There is no way to load a model library while a simulation is running.

Prerequisites

Section titled “Prerequisites”
  • gfortran (GNU Fortran compiler)
  • OpenBLAS (optimized BLAS library)
  • stepss
Terminal window
sudo apt install gfortran make libopenblas-dev

Debian and Ubuntu are the Linux distributions STEPSS is built and tested on; see Installation. The kit itself needs only gfortran, GNU make and OpenBLAS, so it will build wherever those exist, but the compiler has to match the ABI of the bundled .mod files and that is checked against the distributions above.

Project Structure

Section titled “Project Structure”

Every platform carries one suffix throughout: l for Linux, m for macOS, wg for Windows/MinGW (gfortran) and wi for Windows/Intel. A module kit and the output directory it builds into always share it.

URAMSES/
├── src/                         # Framework sources (all platforms)
│   ├── c_interface.f90          # C interface for Python integration
│   ├── main.f90                 # Main entry point (executable only)
│   ├── FUNCTIONS_IN_MODELS.f90  # Helper functions for models
│   ├── usr_exc_models.f90       # Exciter model associations
│   ├── usr_inj_models.f90       # Injector model associations
│   ├── usr_tor_models.f90       # Torque model associations
│   ├── usr_twop_models.f90      # Two-port model associations
│   └── usr_dctl_models.f90      # Discrete controller associations
├── custom_models/               # Your own models (all platforms)
│   ├── exc_*.f90                # Exciter models
│   ├── inj_*.f90                # Injector models
│   ├── tor_*.f90                # Torque models
│   ├── twop_*.f90               # Two-port models
│   └── *.txt                    # Model parameter files
├── modules_l/                   # Pre-compiled kit (Linux/gfortran)
│   ├── *.mod                    # Module interface files
│   └── libramses.a              # Pre-compiled RAMSES library
├── modules_m/                   # Pre-compiled kit (macOS arm64/gfortran)
│   ├── *.mod                    # Module interface files
│   └── libramses.a              # Pre-compiled RAMSES library
├── modules_wg/                  # Pre-compiled kit (Windows/MinGW gfortran)
│   ├── *.mod                    # Module interface files
│   └── libramses.lib            # Pre-compiled RAMSES library
├── modules_wi/                  # Pre-compiled kit (Windows/Intel Fortran)
│   ├── *.mod                    # Module interface files
│   └── libramses.lib            # Pre-compiled RAMSES library
├── build/                       # All build files
│   ├── Makefile.linux           # Linux builds
│   ├── Makefile.macos           # macOS builds (Apple Silicon)
│   ├── Makefile.windows         # Windows/MinGW builds
│   └── msvs/                    # Visual Studio files (Windows/Intel)
│       └── URAMSES.sln          # Visual Studio solution
├── tools/                       # Kit-verification and release helpers
├── Release_l/                   # Build output (Linux)
├── Release_m/                   # Build output (macOS)
├── Release_wg/                  # Build output (Windows/MinGW)
└── Release_wi/                  # Build output (Windows/Intel)

Each platform links its own pre-compiled RAMSES kit, published with the matching RAMSES release as uramses-modules_{l,m,wg}-<version>.zip.

Model Types

Section titled “Model Types”
TypePrefixDescription
Excitersexc_*Generator excitation system models
Injectorsinj_*Current/voltage injection models
Torquetor_*Mechanical torque models
Two-porttwop_*Two-port network models (SVC, STATCOM, HVDC)
Discrete Controldctl_*Discrete control system models

Building

Section titled “Building”

Run from the repository root:

Terminal window
# Build shared library + executable
make -f build/Makefile.linux all


# Build only the shared library (for stepss)
make -f build/Makefile.linux dll


# Build only the executable
make -f build/Makefile.linux exe


# Verify gfortran, OpenBLAS and the module kit
make -f build/Makefile.linux check-deps


# Clean build artifacts
make -f build/Makefile.linux clean

The shared library (ramses.so) will be in Release_l/.

Adding Custom Models

Section titled “Adding Custom Models”

  1. Write the model source: Create a .f90 file in custom_models/ following the naming convention (exc_, inj_, tor_, twop_, or dctl_ prefix)

  2. Register the model: Add the model association in the corresponding usr_*_models.f90 file in src/

  3. Rebuild: Compile and link the modified URAMSES with the Makefile for your platform (build/Makefile.linux, build/Makefile.macos or build/Makefile.windows), which picks up new .f90 files in custom_models/ automatically. Only the Intel Visual Studio route needs the file added to the project by hand.

Example: Registering an Exciter Model

Section titled “Example: Registering an Exciter Model”

In src/usr_exc_models.f90, declare the subroutine and point the model pointer at it. The case label carries the exc_ prefix, because the router has already added it to whatever name the data file used:

   external :: exc_MY_EXCITER
   ...
   select case (modelname4)
      case('exc_MY_EXCITER')
         exc_ptr=>exc_MY_EXCITER

The other four routers follow the same shape, with tor_, inj_, twop_ and dctl_ prefixes and their own pointer names. A data file then refers to the model as either MY_EXCITER or exc_MY_EXCITER.

Up to RAMSES 3.78 this was also how you reached a model that RAMSES compiled but registered under no name, such as exc_AC8B or twop_HVDC_VSC. From 3.79 every compiled model is registered, so that step is no longer needed. The technique still works for anything you want to expose under a second name: the subroutine is already in libramses, so no external declaration or source file of your own is required.

Included Example Models

Section titled “Included Example Models”

The repository includes these example models:

FileDescription
exc_ENTSOE_lim.f90ENTSO-E exciter with limits
inj_AIR_COND1_mod.f90Air conditioning load injector

Using Custom Models

Section titled “Using Custom Models”

With stepss

Section titled “With stepss”

Point stepss to your custom library:

import stepss
ram = stepss.sim(custLibDir="path/to/Release_l")     # Linux
# ram = stepss.sim(custLibDir="path/to/Release_m")   # macOS
# ram = stepss.sim(custLibDir=r"path\to\Release_wg") # Windows (MinGW)
# ram = stepss.sim(custLibDir=r"path\to\Release_wi") # Windows (Intel)

stepss loads ramses.so on Linux and macOS, and ramses.dll on Windows.

With STEPSS GUI

Section titled “With STEPSS GUI”

The Codegen tab does this for you: it runs CODEGEN on your model description, then drives these same Makefiles against the bundled URAMSES kit to produce a custom dynsim, which it uses for subsequent simulations. You need gfortran, GNU make and OpenBLAS installed; see Installation. Building by hand and replacing the simulator manually is only necessary for models the Codegen tab cannot generate.

Helper Functions

Section titled “Helper Functions”

The FUNCTIONS_IN_MODELS.f90 module provides utility functions available in all models. See the Functions Reference for the complete list with signatures.

Repository

Section titled “Repository”

Source code: SPS-L/stepss-uramses