# dvcompute_dist

This crate is a part of discrete event simulation framework DVCompute Simulator (registration
number 2021660590 of Rospatent). The `dvcompute_dist` crate is destined for optimistic
distributed simulation, but the same code base is shared by the `dvcompute_branch` crate destined for nested simulation.

There are the following main crates: `dvcompute` (sequential simulation),
`dvcompute_dist` (optimistic distributed simulation),
`dvcompute_cons` (conservative distributed simulation) and
`dvcompute_branch` (nested simulation). All four crates are
very close. They are based on the same method.

## Requirements

In case of optimistic distributed simulation, it is expected that the `dvcompute_mpi`
and `dvcompute_core_dist` dynamic (shared) libraries can be found by the operating system, when
launching the executable file of the simulation model. 

You can build the `dvcompute_mpi` library yourself from the 
[sources](https://gitflic.ru/project/dsorokin/dvcompute/file?file=src%2Fdvcompute_mpi_cdylib)
that require CMake, C++ compiler and some MPI implementation that you are going to use.

But the `dvcompute_core_dist` dynamic library must satisfy the predefined binary interface as 
specified in the `dvcompute_dist` crate (the dynamic library must implement the event queue). 
You can request the author for the prebuilt version that implements this interface. 
This prebuilt version is a part of "Redistributable Code" portions of DVCompute Simulator.

## Simulation Method

The main idea is to use continuations for modeling discontinuous processes. Such continuations are
themselves wrapped in the monad, for which there are easy-to-use combinators. This idea is inspired
by two sources: (1) combinators for futures that were in Rust before introducing the async/await 
syntax and (2) the Aivika simulation library that I developed in Haskell before.

Here is an example that defines a model of the machine that breaks down and then it is repaired:

```rust
const UP_TIME_MEAN: f64 = 1.0;
const REPAIR_TIME_MEAN: f64 = 0.5;

fn machine_process(total_up_time: Grc<RefComp<f64>>) -> ProcessBox<()> {
    let total_up_time2 = total_up_time.clone();
    random_exponential_process(UP_TIME_MEAN)
        .and_then(move |up_time| {
            RefComp::modify(total_up_time, move |total_up_time| {
                total_up_time + up_time
            })
            .into_process()
            .and_then(move |()| {
                random_exponential_process_(REPAIR_TIME_MEAN)
            })
            .and_then(move |()| {
                machine_process(total_up_time2)
            })
        })
        .into_boxed()
}
```
 
These computations are combined with help of the monadic bind. Such computations should be run later 
to take effect.

## Examples

You can find examples in the author's [repository](https://gitflic.ru/project/dsorokin/dvcompute).

## Documentation

* [API docs](https://docs.rs/dvcompute_dist/)

## Tutorial

Also you can read the PDF document [DVCompute Simulator Tutorial](https://gitflic.ru/project/dsorokin/dvcompute/blob?file=doc%2Fdvcompute-tutorial.pdf).

## Bibliography

* Sorokin David. DVCompute Simulator for discrete event simulation.
  Prikladnaya informatika=Journal of Applied Informatics, 2021, vol.16, no.3, pp.93-108 (in Russian).
  DOI: 10.37791/2687-0649-2021-16-3-93-108

## Licence

Copyright 2020-2024 David Sorokin <davsor@mail.ru>, based in Yoshkar-Ola, Russia

This software is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at <http://mozilla.org/MPL/2.0/>.