outcome simulation engine
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


simulation engine

outcome-sim is the base simulation engine library for the outcome project.

It's used in other programs like the command-line utility endgame.

Check out theoutcomeproject.com to learn more.


outcome-sim exposes the basic interface needed to generate, run and interact with outcome simulations.

Here’s a simplistic example of how you would parse and run a simulation using outcome-sim in your rust project.

extern crate outcome_sim as outcome;

use outcome::core::{SimInstance, Address};

fn main() {
    let path_to_scenario = "/path/to/scenario";
    let sim_instance = SimInstance::new_from_scenario_path(path_to_scenario);
    // process in a loop
    loop {
        // process one base tick (hour)
        // get some data from the simulation and print it out
        let addr = Address::from_str_global("/region/e01001/generic/test_element/int/int_var").unwrap();
        match sim_instance.db.get_int(&addr) {
            Some(i) => println!("{}", i),
            None => println!("Couldn\'t get the integer at {}", addr.to_string()),
        println!("Processed single tick");


outcome-sim uses log crate for logging useful errors, warnings and other information, especially during things like parsing user data and creating simulation instance. Here's an example of how to capture logs with simplelog crate.

use simplelog::{TermLogger, Config};

fn main() {
    // initialize logger, print everything
    TermLogger::init(LevelFilter::max(), Config::default()).unwrap();

    // do something with outcome-sim,
    // like in the example from the previous paragraph


There are some examples included in the examples directory. Use cargo to run them from the command line:

cargo run --example <example_name_without_extension>

Add a --release flag to compile with optimizations (improved performance, compilation will take a while longer).


  • the main object exposed by the library is the SimInstance
  • a central Database is created and maintained inside the SimInstance object, it serves as a high-level abstraction for getting data from inside the simulation
  • data and instructions are initially read from user modfiles and stored inside the SimInstance in form of hierarchically defined objects
  • instructions hierarchy
    • entity -> element -> state -> command
  • variables hierarchy
    • entity -> element -> variable (though technically variables are stored at the level of the entity)
  • entity objects are used for division of processing work
    • each entity "owns" it's own variables database
    • entities are sent to different threads for processing, there are some caveats though regarding accessing data for processing
      • reading data from other entities has to be signalled beforehand so a list of variables to be copied can be prepared
      • writing data to other entities has to be done in the main thread (this is signified with ext_ in command names, which stands for "external")
      • reading and writing data within the context of the entity ("locally") is always fine