bourse-de 0.4.0

Discrete event market simulation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Simulation agent traits and common implementations
//!
//! The simulation agents must implement an `update` function
//! that is called each step of the simulation.
//!
use super::env::Env;
use rand::RngCore;
pub mod common;
mod momentum_agent;
mod noise_agent;
mod random_agent;

pub use bourse_macros::Agents;
pub use momentum_agent::{MomentumAgent, MomentumParams};
pub use noise_agent::{NoiseAgent, NoiseAgentParams};
pub use random_agent::RandomAgents;

/// Homogeneous agent set functionality
///
/// A set of agents that implement this trait
/// can then be included in a struct using the
/// [Agents] macro to combine multiple agent
/// types.
///
/// # Examples
///
/// ```
/// use bourse_de::Env;
/// use bourse_de::agents::{Agent, Agents, AgentSet};
/// use rand::RngCore;
///
/// struct AgentType{}
///
/// impl Agent for AgentType {
///     fn update<R: RngCore>(
///         &mut self, env: &mut Env, _rng: &mut R
///     ) {}
/// }
///
/// #[derive(Agents)]
/// struct MixedAgents {
///     a: AgentType, b: AgentType
/// }
/// ```
pub trait Agent {
    /// Update the state of the agent(s)
    ///
    /// # Argument
    ///
    /// - `env` - Reference to a [Env] simulation environment
    /// - `rng` - Random generator
    ///
    fn update<R: RngCore>(&mut self, env: &mut Env, rng: &mut R);
}

/// Functionality required for simulation agents
///
/// Simulation agents provided as an argument to
/// [crate::sim_runner] must implement this trait,
/// but the details of the implementation are
/// left to the user.
///
/// It's a common case that we want update to update
/// a heterogeneous set of agents which can be
/// automatically implemented with the [Agents] macro
/// as long as the agent types implement the [Agent]
/// trait.
///
/// # Examples
///
/// ```
/// use bourse_de::Env;
/// use bourse_de::agents::{Agent, Agents, AgentSet};
/// use rand::RngCore;
///
/// struct AgentType{}
///
/// impl Agent for AgentType {
///     fn update<R: RngCore>(
///         &mut self, env: &mut Env, _rng: &mut R
///     ) {}
/// }
///
/// #[derive(Agents)]
/// struct MixedAgents {
///     a: AgentType,
///     b: AgentType
/// }
/// ```
///
/// this is equivalent to
///
/// ```
/// # use bourse_de::Env;
/// # use bourse_de::agents::{Agent, Agents, AgentSet};
/// # use rand::RngCore;
/// # struct AgentType{}
/// # impl Agent for AgentType {
/// #    fn update<R: RngCore>(
/// #        &mut self, env: &mut Env, _rng: &mut R
/// #     ) {}
/// # }
/// struct MixedAgents {
///     a: AgentType,
///     b: AgentType
/// }
///
/// impl AgentSet for MixedAgents {
///     fn update<R: RngCore>(&mut self, env: &mut Env, rng: &mut R){
///         self.a.update(env, rng);
///         self.b.update(env, rng);
///     }
/// }
/// ```
pub trait AgentSet {
    /// Update function called each simulated step
    ///
    /// This function should update the state of the
    /// agent(s) and submit transactions to the
    /// simulation environment
    ///
    /// The implementing struct is flexible in what
    /// it represent, from a single agent to a group
    /// of multiple agent types.
    ///
    /// # Arguments
    ///
    /// - `env` - Simulation environment
    /// - `rng` - Random generator
    ///
    fn update<R: RngCore>(&mut self, env: &mut Env, rng: &mut R);
}