Getting Started

This guide will help you get up and running with OpenSEFA.jl.

Installation

To install this package, clone the repository and instantiate it using the Julia package manager:

$ git clone https://github.com/MatplusGmbH/opensefa-reconciliation-solver.git
$ cd opensefa-reconciliation-solver
$ julia --project

In the Julia REPL, activate the package manager mode by typing ], then instantiate:

julia> ]
pkg> instantiate

This downloads and precompiles all dependencies. The first time this runs, it may take a few minutes.

Note

The instantiate command is only required once, or when dependencies change.

Basic Workflow

Solving a data reconciliation problem with OpenSEFA.jl involves three main steps:

1. Specification

Load your model data into the internal representation (ReconciliationProblem). You can do this by:

  • Defining problems programmatically in Julia
  • Loading from STAN trace files
  • Loading from JSON format
  • Using the HTTP API

2. Solution

Solve the reconciliation problem using default or custom algorithm choices to obtain a ReconciliationSolution.

3. Validation

Verify the quality of the solution by examining:

  • Residual terms magnitude
  • Constraint satisfaction
  • Objective value

You can iterate between steps 2 and 3, adjusting solver settings as needed.

Quick Example

Here's a complete example that loads and solves a simple problem:

# Load the package
using OpenSEFA

# Load the seven flows example from the test suite
include(joinpath(MODELS_PATH, "seven_flows.jl"))

# Parse the equations and load into Julia data structures
rec = seven_flows_cencic_2012()

# Solve the problem with the default algorithm
sol = solve(rec)

The rec object shows the problem structure:

julia> rec
• Data reconciliation optimization problem with:
  • Name: Seven flows Cencic2016
  • Equations: 4
  • Variables: 8
    • Measured: 4
    • Unmeasured: 3
    • Fixed: 1

The sol object contains the solution:

julia> sol
• Solution of data reconciliation optimization problem with:
  • Name: Seven flows Cencic2016
  • Equations: 4
  • Variables: 8
    • Measured: 4
    • Unmeasured: 3
    • Fixed: 1
  • Objective value: 0.2959
  • Status: FEASIBLE_WITH_UNOBSERVABLE_VARIABLES
  • Globality proven: false
  • Solution score:
    • Percentage of solved variables: 1.0
    • Percentage of assigned variables: 1.0
    • Percentage of uniquely solved variables: 0.75
    • Percentage of solved equations: 1.0
    • Residual: 3.0145e-8
    • Max relative residual: 4.1816e-13

Loading STAN Models

OpenSEFA.jl can import models from STAN software. There are two main approaches:

Loading STAN Data (CSV files)

Export your data from STAN's data explorer to CSV files, then:

using OpenSEFA

path = joinpath(MODELS_PATH, "Cencic_2016_STAN")
sdata = load_stan_data(path)

This loads all flows and variable specifications into a STANData structure.

Loading STAN Trace Files

To load a complete assembled model from STAN:

  1. Run the STAN solver with the verbose option for printing equations enabled
  2. Save all results from the trace console into a trace.txt file in your model directory
  3. Load and solve:
using OpenSEFA

path = joinpath(MODELS_PATH, "Cencic_2016_STAN")
strace = parse(STANTrace, path)
rec = convert(ReconciliationProblem, strace)
sol = solve(rec)

Running Tests

To verify your installation, run the test suite:

# From the Julia REPL with OpenSEFA activated:
julia> ]
pkg> test

Or from the terminal:

$ julia --project test/runtests.jl

Next Steps

  • Explore Examples for more complex use cases
  • Learn about the HTTP API for web integration
  • Check the API Reference for detailed function documentation
  • Read the References for theoretical background