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 --projectIn the Julia REPL, activate the package manager mode by typing ], then instantiate:
julia> ]
pkg> instantiateThis downloads and precompiles all dependencies. The first time this runs, it may take a few minutes.
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: 1The 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-13Loading 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:
- Run the STAN solver with the verbose option for printing equations enabled
- Save all results from the trace console into a
trace.txtfile in your model directory - 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> testOr from the terminal:
$ julia --project test/runtests.jlNext 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