bandit_machines 0.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +95 -0
- data/Cargo.lock +321 -0
- data/Cargo.toml +29 -0
- data/LICENSE.txt +21 -0
- data/README.md +367 -0
- data/ext/bandit_machines_native/core/CHANGELOG.md +70 -0
- data/ext/bandit_machines_native/core/Cargo.toml +21 -0
- data/ext/bandit_machines_native/core/README.md +152 -0
- data/ext/bandit_machines_native/core/src/bandit.rs +576 -0
- data/ext/bandit_machines_native/core/src/lib.rs +286 -0
- data/ext/bandit_machines_native/core/src/math.rs +66 -0
- data/ext/bandit_machines_native/core/src/pick.rs +71 -0
- data/ext/bandit_machines_native/extconf.rb +2 -0
- data/ext/bandit_machines_native/ffi/Cargo.toml +21 -0
- data/ext/bandit_machines_native/ffi/extconf.rb +14 -0
- data/ext/bandit_machines_native/ffi/src/convert.rs +238 -0
- data/ext/bandit_machines_native/ffi/src/init.rs +128 -0
- data/ext/bandit_machines_native/ffi/src/lib.rs +246 -0
- data/lib/bandit_machines/version.rb +5 -0
- data/lib/bandit_machines.rb +74 -0
- data/sig/bandit_machines.rbs +157 -0
- metadata +87 -0
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
//! Strict Ruby-to-core conversions and the symbols refusals come back as.
|
|
2
|
+
|
|
3
|
+
use bandit_machines::{
|
|
4
|
+
ArmStats, Closing, Config, Draws, Opening, Ratio, Reason, Refusal, TieBreak,
|
|
5
|
+
};
|
|
6
|
+
use magnus::{
|
|
7
|
+
Error, IntoValue, RClass, RModule, RStruct, Ruby, TryConvert, Value, prelude::*,
|
|
8
|
+
typed_data::Obj,
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
use crate::Handle;
|
|
12
|
+
use matryona_machines::ruby::{
|
|
13
|
+
Class, Symbols, boolean, class_name, exact_fields, exact_typed_with, integer,
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
/// Every class the binding builds or checks, as resolved at init.
|
|
17
|
+
pub struct Classes {
|
|
18
|
+
pub config: Class,
|
|
19
|
+
pub ratio: Class,
|
|
20
|
+
pub draws: Class,
|
|
21
|
+
pub selection: Class,
|
|
22
|
+
pub arm_stats: Class,
|
|
23
|
+
pub ticket: Class,
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
matryona_machines::registry! {
|
|
27
|
+
static CLASSES: Classes = "bandit_machines";
|
|
28
|
+
pub fn classes;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/// Resolves and pins every class, once: `ticket`, which `init` defined, as
|
|
32
|
+
/// given, with no lookup back by name, fixing magnus's class for `Handle` to
|
|
33
|
+
/// it (no ticket conversion runs `Object.const_get` later); the rest, which
|
|
34
|
+
/// `lib/bandit_machines.rb` defined, by name.
|
|
35
|
+
pub fn resolve(ruby: &Ruby, module: RModule, ticket: RClass) -> Result<(), Error> {
|
|
36
|
+
let class = |name| Class::resolve(ruby, module, name);
|
|
37
|
+
let classes = Classes {
|
|
38
|
+
config: class("Config")?,
|
|
39
|
+
ratio: class("Ratio")?,
|
|
40
|
+
draws: class("Draws")?,
|
|
41
|
+
selection: class("Selection")?,
|
|
42
|
+
arm_stats: class("ArmStats")?,
|
|
43
|
+
ticket: Class::pin_wrapped::<Handle>(ruby, ticket)?,
|
|
44
|
+
};
|
|
45
|
+
CLASSES.set(ruby, classes).map(drop)
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/// Build one of the gem's `Data` values natively from what the core answered:
|
|
49
|
+
/// allocate, fill the members by position, freeze. That is all
|
|
50
|
+
/// `Data#initialize` does past the check, and the core's own answers need no
|
|
51
|
+
/// check, so no Ruby code runs.
|
|
52
|
+
pub fn build<const N: usize>(class: RClass, members: [Value; N]) -> Result<Value, Error> {
|
|
53
|
+
let instance = RStruct::try_convert(class.obj_alloc()?)?;
|
|
54
|
+
for (index, member) in members.into_iter().enumerate() {
|
|
55
|
+
instance.aset(index, member)?;
|
|
56
|
+
}
|
|
57
|
+
instance.freeze();
|
|
58
|
+
Ok(instance.as_value())
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/// The members of `value`, which must be an instance of exactly `class` (a
|
|
62
|
+
/// subclass's constant leaks past the seal). Read straight from the struct,
|
|
63
|
+
/// so no reader runs; `Marshal.load` skips `initialize`, so every caller
|
|
64
|
+
/// converts each member again through the core's types.
|
|
65
|
+
fn members<const N: usize>(
|
|
66
|
+
ruby: &Ruby,
|
|
67
|
+
value: Value,
|
|
68
|
+
class: Class,
|
|
69
|
+
message: &'static str,
|
|
70
|
+
) -> Result<[Value; N], Error> {
|
|
71
|
+
exact_fields(ruby, value, class.get(ruby), message)
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
pub fn ratio(ruby: &Ruby, value: Value) -> Result<Ratio, Error> {
|
|
75
|
+
let class = classes(ruby)?.ratio;
|
|
76
|
+
let [numerator, denominator] = members(ruby, value, class, "expected a BanditMachines::Ratio")?;
|
|
77
|
+
let numerator = integer(numerator, "numerator")?;
|
|
78
|
+
let denominator = integer(denominator, "denominator")?;
|
|
79
|
+
Ratio::new(numerator, denominator).ok_or_else(|| {
|
|
80
|
+
Error::new(
|
|
81
|
+
ruby.exception_range_error(),
|
|
82
|
+
"ratio needs 0 <= numerator <= denominator and denominator > 0",
|
|
83
|
+
)
|
|
84
|
+
})
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
pub fn ratio_value(ruby: &Ruby, ratio: Ratio) -> Result<Value, Error> {
|
|
88
|
+
let members = [ratio.numerator(), ratio.denominator()].map(|term| term.into_value_with(ruby));
|
|
89
|
+
build(classes(ruby)?.ratio.get(ruby), members)
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
pub fn draws(ruby: &Ruby, value: Value) -> Result<Draws, Error> {
|
|
93
|
+
let class = classes(ruby)?.draws;
|
|
94
|
+
let [gate, pick] = members(ruby, value, class, "expected a BanditMachines::Draws")?;
|
|
95
|
+
let (gate, pick) = (integer(gate, "gate")?, integer(pick, "pick")?);
|
|
96
|
+
Ok(Draws { gate, pick })
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
matryona_machines::symbols! {
|
|
100
|
+
/// How a tie between equal arms is broken, as `Config#tie_break` holds it.
|
|
101
|
+
pub TieBreaks for TieBreak as "tie_break" {
|
|
102
|
+
LowestIndex => "lowest_index",
|
|
103
|
+
HighestIndex => "highest_index",
|
|
104
|
+
LeastTried => "least_tried",
|
|
105
|
+
Draw => "draw",
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
matryona_machines::symbols! {
|
|
110
|
+
/// Why an arm was selected, as `Selection#reason` holds it.
|
|
111
|
+
pub Reasons for Reason as "reason" {
|
|
112
|
+
ColdStart => "cold_start",
|
|
113
|
+
Explore => "explore",
|
|
114
|
+
Exploit => "exploit",
|
|
115
|
+
UpperBound => "upper_bound",
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
matryona_machines::symbols! {
|
|
120
|
+
/// A refusal as its Symbol: the snake case of the core variant.
|
|
121
|
+
pub Refusals for Refusal as "refusal" {
|
|
122
|
+
UnknownArm => "unknown_arm",
|
|
123
|
+
NoOpenArm => "no_open_arm",
|
|
124
|
+
TicketsFull => "tickets_full",
|
|
125
|
+
Exhausted => "exhausted",
|
|
126
|
+
StaleTicket => "stale_ticket",
|
|
127
|
+
UnknownTicket => "unknown_ticket",
|
|
128
|
+
RewardOutOfRange => "reward_out_of_range",
|
|
129
|
+
Saturated => "saturated",
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
pub fn config(ruby: &Ruby, value: Value) -> Result<Config, Error> {
|
|
134
|
+
let class = classes(ruby)?.config;
|
|
135
|
+
let [max_reward, prior, rule] =
|
|
136
|
+
members(ruby, value, class, "expected a BanditMachines::Config")?;
|
|
137
|
+
let (max_reward, prior) = (integer(max_reward, "max_reward")?, integer(prior, "prior")?);
|
|
138
|
+
let rule = TieBreaks::parse(ruby, rule)?;
|
|
139
|
+
Config::new(max_reward, prior, rule).ok_or_else(|| {
|
|
140
|
+
Error::new(
|
|
141
|
+
ruby.exception_range_error(),
|
|
142
|
+
"max_reward must be positive and prior at most max_reward",
|
|
143
|
+
)
|
|
144
|
+
})
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
pub fn config_value(ruby: &Ruby, config: Config) -> Result<Value, Error> {
|
|
148
|
+
build(
|
|
149
|
+
classes(ruby)?.config.get(ruby),
|
|
150
|
+
[
|
|
151
|
+
config.max_reward().into_value_with(ruby),
|
|
152
|
+
config.prior().into_value_with(ruby),
|
|
153
|
+
TieBreaks::symbol(ruby, config.tie_break()).as_value(),
|
|
154
|
+
],
|
|
155
|
+
)
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
pub fn stats_value(ruby: &Ruby, stats: ArmStats) -> Result<Value, Error> {
|
|
159
|
+
build(
|
|
160
|
+
classes(ruby)?.arm_stats.get(ruby),
|
|
161
|
+
[
|
|
162
|
+
stats.open.into_value_with(ruby),
|
|
163
|
+
stats.generation.into_value_with(ruby),
|
|
164
|
+
stats.rewarded.into_value_with(ruby),
|
|
165
|
+
stats.reward_sum.into_value_with(ruby),
|
|
166
|
+
stats.pending.into_value_with(ruby),
|
|
167
|
+
],
|
|
168
|
+
)
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/// Build a `Selection` natively, with the class resolved at init: nothing
|
|
172
|
+
/// after the core's answer runs Ruby code.
|
|
173
|
+
pub fn selection_value(
|
|
174
|
+
ruby: &Ruby,
|
|
175
|
+
class: RClass,
|
|
176
|
+
ticket: Value,
|
|
177
|
+
why: Reason,
|
|
178
|
+
) -> Result<Value, Error> {
|
|
179
|
+
build(class, [ticket, Reasons::symbol(ruby, why).as_value()])
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/// Check a hand-built `Selection`: the ticket a `Ticket`, the reason one of
|
|
183
|
+
/// the core's variants. Every such pair is a selection the core could answer.
|
|
184
|
+
pub fn selection(ruby: &Ruby, value: Value) -> Result<(), Error> {
|
|
185
|
+
let known = classes(ruby)?;
|
|
186
|
+
let [ticket, why] = members(
|
|
187
|
+
ruby,
|
|
188
|
+
value,
|
|
189
|
+
known.selection,
|
|
190
|
+
"expected a BanditMachines::Selection",
|
|
191
|
+
)?;
|
|
192
|
+
self::ticket(ruby, ticket)?;
|
|
193
|
+
Reasons::parse(ruby, why).map(drop)
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/// Check a hand-built `ArmStats`: `open` a boolean, every count an unsigned
|
|
197
|
+
/// 64-bit Integer. The core's snapshot has no further invariant.
|
|
198
|
+
pub fn arm_stats(ruby: &Ruby, value: Value) -> Result<(), Error> {
|
|
199
|
+
let class = classes(ruby)?.arm_stats;
|
|
200
|
+
let [open, counts @ ..] =
|
|
201
|
+
members::<5>(ruby, value, class, "expected a BanditMachines::ArmStats")?;
|
|
202
|
+
boolean(open, "open")?;
|
|
203
|
+
let names = ["generation", "rewarded", "reward_sum", "pending"];
|
|
204
|
+
for (count, name) in counts.into_iter().zip(names) {
|
|
205
|
+
integer::<u64>(count, name)?;
|
|
206
|
+
}
|
|
207
|
+
Ok(())
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/// The ticket `value` wraps: exactly a `BanditMachines::Ticket`, a subclass
|
|
211
|
+
/// instance refused with `TypeError` naming the class received.
|
|
212
|
+
pub fn ticket(ruby: &Ruby, value: Value) -> Result<Obj<Handle>, Error> {
|
|
213
|
+
let class = classes(ruby)?.ticket.get(ruby);
|
|
214
|
+
exact_typed_with(ruby, value, class, || {
|
|
215
|
+
format!(
|
|
216
|
+
"ticket must be a BanditMachines::Ticket, not {}",
|
|
217
|
+
class_name(value)
|
|
218
|
+
)
|
|
219
|
+
})
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
pub const fn opening(opening: Opening) -> &'static str {
|
|
223
|
+
match opening {
|
|
224
|
+
Opening::Opened => "opened",
|
|
225
|
+
Opening::AlreadyOpen => "already_open",
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
pub const fn closing(closing: Closing) -> &'static str {
|
|
230
|
+
match closing {
|
|
231
|
+
Closing::Closed => "closed",
|
|
232
|
+
Closing::AlreadyClosed => "already_closed",
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
pub fn refusal(ruby: &Ruby, refusal: Refusal) -> Value {
|
|
237
|
+
Refusals::symbol(ruby, refusal).as_value()
|
|
238
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
//! Private native entry point.
|
|
2
|
+
use bandit_machines::{Ratio, math};
|
|
3
|
+
use magnus::{Error, Ruby, Value, function, method, prelude::*};
|
|
4
|
+
|
|
5
|
+
use crate::convert;
|
|
6
|
+
use crate::{Bandit, Engine, Handle};
|
|
7
|
+
use matryona_machines::ruby::{Class, integer};
|
|
8
|
+
|
|
9
|
+
fn validate_config(ruby: &Ruby, this: Value) -> Result<(), Error> {
|
|
10
|
+
convert::config(ruby, this).map(|_| ())
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
fn validate_ratio(ruby: &Ruby, this: Value) -> Result<(), Error> {
|
|
14
|
+
convert::ratio(ruby, this).map(|_| ())
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
fn validate_selection(ruby: &Ruby, this: Value) -> Result<(), Error> {
|
|
18
|
+
convert::selection(ruby, this)
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
fn validate_arm_stats(ruby: &Ruby, this: Value) -> Result<(), Error> {
|
|
22
|
+
convert::arm_stats(ruby, this)
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
fn validate_draws(ruby: &Ruby, this: Value) -> Result<(), Error> {
|
|
26
|
+
convert::draws(ruby, this).map(|_| ())
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
fn log2_q56(value: Value) -> Result<u64, Error> {
|
|
30
|
+
integer(value, "value").map(math::log2_q56)
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
fn ln_q56(value: Value) -> Result<u64, Error> {
|
|
34
|
+
integer(value, "value").map(math::ln_q56)
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
fn bonus_q56(total: Value, tries: Value) -> Result<u64, Error> {
|
|
38
|
+
Ok(math::bonus_q56(
|
|
39
|
+
integer(total, "total")?,
|
|
40
|
+
integer(tries, "tries")?,
|
|
41
|
+
))
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
fn mean_q56(sum: Value, count: Value, range: Value) -> Result<u64, Error> {
|
|
45
|
+
let (sum, count) = (integer(sum, "sum")?, integer(count, "count")?);
|
|
46
|
+
Ok(math::mean_q56(sum, count, integer(range, "range")?))
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/// The checks of the `Data` values defined in Ruby, and the core's constants.
|
|
50
|
+
fn values(ruby: &Ruby) -> Result<(), Error> {
|
|
51
|
+
let classes = convert::classes(ruby)?;
|
|
52
|
+
classes
|
|
53
|
+
.config
|
|
54
|
+
.get(ruby)
|
|
55
|
+
.define_private_method("__validate", method!(validate_config, 0))?;
|
|
56
|
+
classes
|
|
57
|
+
.draws
|
|
58
|
+
.get(ruby)
|
|
59
|
+
.define_private_method("__validate", method!(validate_draws, 0))?;
|
|
60
|
+
classes
|
|
61
|
+
.selection
|
|
62
|
+
.get(ruby)
|
|
63
|
+
.define_private_method("__validate", method!(validate_selection, 0))?;
|
|
64
|
+
classes
|
|
65
|
+
.arm_stats
|
|
66
|
+
.get(ruby)
|
|
67
|
+
.define_private_method("__validate", method!(validate_arm_stats, 0))?;
|
|
68
|
+
let ratio = classes.ratio.get(ruby);
|
|
69
|
+
ratio.define_private_method("__validate", method!(validate_ratio, 0))?;
|
|
70
|
+
ratio.const_set("ZERO", convert::ratio_value(ruby, Ratio::ZERO)?)?;
|
|
71
|
+
ratio.const_set("ONE", convert::ratio_value(ruby, Ratio::ONE)?)?;
|
|
72
|
+
Ok(())
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
#[magnus::init]
|
|
76
|
+
fn init(ruby: &Ruby) -> Result<(), Error> {
|
|
77
|
+
let module = ruby.define_module("BanditMachines")?;
|
|
78
|
+
|
|
79
|
+
let math = module.define_module("Math")?;
|
|
80
|
+
math.const_set("FRACTION_BITS", math::FRACTION_BITS)?;
|
|
81
|
+
math.const_set("ONE", math::ONE)?;
|
|
82
|
+
math.define_singleton_method("log2_q56", function!(log2_q56, 1))?;
|
|
83
|
+
math.define_singleton_method("ln_q56", function!(ln_q56, 1))?;
|
|
84
|
+
math.define_singleton_method("bonus_q56", function!(bonus_q56, 2))?;
|
|
85
|
+
math.define_singleton_method("mean_q56", function!(mean_q56, 3))?;
|
|
86
|
+
|
|
87
|
+
// Before the values: `Selection` checks its ticket against this class.
|
|
88
|
+
let handle = module.define_class("Ticket", ruby.class_object())?;
|
|
89
|
+
handle.undef_default_alloc_func();
|
|
90
|
+
handle.define_method("arm", method!(Handle::arm, 0))?;
|
|
91
|
+
handle.define_method("generation", method!(Handle::generation, 0))?;
|
|
92
|
+
handle.define_method("serial", method!(Handle::serial, 0))?;
|
|
93
|
+
handle.define_method("scope", method!(Handle::scope, 0))?;
|
|
94
|
+
convert::resolve(ruby, module, handle)?;
|
|
95
|
+
values(ruby)?;
|
|
96
|
+
|
|
97
|
+
let class = module.define_class("Bandit", ruby.class_object())?;
|
|
98
|
+
class.undef_default_alloc_func();
|
|
99
|
+
class.const_set("ARMS", Engine::ARMS)?;
|
|
100
|
+
class.const_set("TICKETS", Engine::TICKETS)?;
|
|
101
|
+
class.define_singleton_method("new", function!(Bandit::new, 1))?;
|
|
102
|
+
class.define_singleton_method("with_scope", function!(Bandit::with_scope, 2))?;
|
|
103
|
+
class.define_singleton_method("resumed", function!(Bandit::resumed, 3))?;
|
|
104
|
+
class.define_method("scope", method!(Bandit::scope, 0))?;
|
|
105
|
+
class.define_method("issued", method!(Bandit::issued, 0))?;
|
|
106
|
+
class.define_method("config", method!(Bandit::config, 0))?;
|
|
107
|
+
class.define_method("outstanding", method!(Bandit::outstanding, 0))?;
|
|
108
|
+
class.define_method("next_serial", method!(Bandit::next_serial, 0))?;
|
|
109
|
+
class.define_method("stats", method!(Bandit::stats, 1))?;
|
|
110
|
+
class.define_method("open", method!(Bandit::open, 1))?;
|
|
111
|
+
class.define_method("close", method!(Bandit::close, 1))?;
|
|
112
|
+
class.define_method("select_ucb1", method!(Bandit::select_ucb1, 1))?;
|
|
113
|
+
class.define_method(
|
|
114
|
+
"select_epsilon_greedy",
|
|
115
|
+
method!(Bandit::select_epsilon_greedy, 2),
|
|
116
|
+
)?;
|
|
117
|
+
class.define_method("ucb1_index_q56", method!(Bandit::ucb1_index_q56, 1))?;
|
|
118
|
+
class.define_method("reward", method!(Bandit::reward, 2))?;
|
|
119
|
+
class.define_method("abandon", method!(Bandit::abandon, 1))?;
|
|
120
|
+
class.define_method("revoke_before", method!(Bandit::revoke_before, 1))?;
|
|
121
|
+
class.define_method("revoke_all", method!(Bandit::revoke_all, 0))?;
|
|
122
|
+
class.define_method("reset", method!(Bandit::reset, 1))?;
|
|
123
|
+
class.define_method("reset_all", method!(Bandit::reset_all, 0))?;
|
|
124
|
+
class.define_method("decay", method!(Bandit::decay, 2))?;
|
|
125
|
+
class.define_method("decay_all", method!(Bandit::decay_all, 1))?;
|
|
126
|
+
// `new` answers a Bandit: its class is fixed now, like the ticket's.
|
|
127
|
+
Class::pin_wrapped::<Bandit>(ruby, class).map(drop)
|
|
128
|
+
}
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
//! Thin binding to the bounded bandit.
|
|
2
|
+
mod convert;
|
|
3
|
+
mod init;
|
|
4
|
+
|
|
5
|
+
use std::cell::RefCell;
|
|
6
|
+
|
|
7
|
+
use bandit_machines::{Bandit as Core, Refusal, Selection, Ticket};
|
|
8
|
+
use magnus::{Error, RClass, Ruby, Symbol, Value, prelude::*, typed_data::Obj};
|
|
9
|
+
use matryona_machines::ruby::{integer, keep, symbol};
|
|
10
|
+
|
|
11
|
+
use convert::refusal;
|
|
12
|
+
|
|
13
|
+
/// The core as compiled for Ruby: 16 arms, 64 outstanding tickets. Everything
|
|
14
|
+
/// else reads the core's `Engine::ARMS` and `Engine::TICKETS`.
|
|
15
|
+
type Engine = Core<16, 64>;
|
|
16
|
+
|
|
17
|
+
/// `BanditMachines::Ticket`: the core's `Ticket`. Its serial carries the
|
|
18
|
+
/// scope of the bandit that issued it; the core refuses it anywhere else.
|
|
19
|
+
#[magnus::wrap(class = "BanditMachines::Ticket", free_immediately, size)]
|
|
20
|
+
struct Handle(Ticket);
|
|
21
|
+
|
|
22
|
+
impl Handle {
|
|
23
|
+
const fn arm(&self) -> usize {
|
|
24
|
+
self.0.arm()
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const fn generation(&self) -> u64 {
|
|
28
|
+
self.0.generation()
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const fn serial(&self) -> u64 {
|
|
32
|
+
self.0.serial()
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const fn scope(&self) -> u16 {
|
|
36
|
+
self.0.scope()
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
#[magnus::wrap(class = "BanditMachines::Bandit", free_immediately, size)]
|
|
41
|
+
struct Bandit {
|
|
42
|
+
core: RefCell<Engine>,
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
impl Bandit {
|
|
46
|
+
/// Every arm starts closed, as in the core. Scope zero.
|
|
47
|
+
fn new(ruby: &Ruby, config: Value) -> Result<Self, Error> {
|
|
48
|
+
let config = convert::config(ruby, config)?;
|
|
49
|
+
Ok(Self {
|
|
50
|
+
core: RefCell::new(Core::new(config)),
|
|
51
|
+
})
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
fn with_scope(ruby: &Ruby, config: Value, scope: Value) -> Result<Self, Error> {
|
|
55
|
+
let scope = integer(scope, "scope")?;
|
|
56
|
+
let config = convert::config(ruby, config)?;
|
|
57
|
+
Ok(Self {
|
|
58
|
+
core: RefCell::new(Core::with_scope(config, scope)),
|
|
59
|
+
})
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
fn resumed(ruby: &Ruby, config: Value, scope: Value, issued: Value) -> Result<Self, Error> {
|
|
63
|
+
let (scope, issued) = (integer(scope, "scope")?, integer(issued, "issued")?);
|
|
64
|
+
let config = convert::config(ruby, config)?;
|
|
65
|
+
let core = Core::resumed(config, scope, issued).ok_or_else(|| {
|
|
66
|
+
Error::new(
|
|
67
|
+
ruby.exception_range_error(),
|
|
68
|
+
"issued is past the last sequence of a scope (2**48 - 1)",
|
|
69
|
+
)
|
|
70
|
+
})?;
|
|
71
|
+
Ok(Self {
|
|
72
|
+
core: RefCell::new(core),
|
|
73
|
+
})
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
fn scope(&self) -> u16 {
|
|
77
|
+
self.core.borrow().scope()
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
fn issued(&self) -> u64 {
|
|
81
|
+
self.core.borrow().issued()
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
fn config(ruby: &Ruby, this: &Self) -> Result<Value, Error> {
|
|
85
|
+
convert::config_value(ruby, this.core.borrow().config())
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/// `class` is `Selection`, resolved at init.
|
|
89
|
+
fn selected(
|
|
90
|
+
ruby: &Ruby,
|
|
91
|
+
class: RClass,
|
|
92
|
+
outcome: Result<Selection, Refusal>,
|
|
93
|
+
) -> Result<Value, Error> {
|
|
94
|
+
match outcome {
|
|
95
|
+
Ok(selection) => {
|
|
96
|
+
let handle = ruby.obj_wrap(Handle(selection.ticket));
|
|
97
|
+
convert::selection_value(ruby, class, handle.as_value(), selection.reason)
|
|
98
|
+
}
|
|
99
|
+
Err(refused) => Ok(refusal(ruby, refused)),
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/// An honoured answer as `honoured` builds it, or the refusal's symbol.
|
|
104
|
+
fn answer<T>(
|
|
105
|
+
ruby: &Ruby,
|
|
106
|
+
outcome: Result<T, Refusal>,
|
|
107
|
+
honoured: impl FnOnce(T) -> Value,
|
|
108
|
+
) -> Value {
|
|
109
|
+
outcome.map_or_else(|refused| refusal(ruby, refused), honoured)
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
fn select_ucb1(ruby: &Ruby, this: Obj<Self>, pick: Value) -> Result<Value, Error> {
|
|
113
|
+
this.check_frozen()?;
|
|
114
|
+
let pick = integer(pick, "pick")?;
|
|
115
|
+
let class = convert::classes(ruby)?.selection.get(ruby);
|
|
116
|
+
keep(
|
|
117
|
+
ruby,
|
|
118
|
+
this,
|
|
119
|
+
&this.core,
|
|
120
|
+
|core| core.select_ucb1(pick),
|
|
121
|
+
|outcome| Self::selected(ruby, class, outcome),
|
|
122
|
+
)
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
fn select_epsilon_greedy(
|
|
126
|
+
ruby: &Ruby,
|
|
127
|
+
this: Obj<Self>,
|
|
128
|
+
epsilon: Value,
|
|
129
|
+
draws: Value,
|
|
130
|
+
) -> Result<Value, Error> {
|
|
131
|
+
this.check_frozen()?;
|
|
132
|
+
let epsilon = convert::ratio(ruby, epsilon)?;
|
|
133
|
+
let draws = convert::draws(ruby, draws)?;
|
|
134
|
+
let class = convert::classes(ruby)?.selection.get(ruby);
|
|
135
|
+
keep(
|
|
136
|
+
ruby,
|
|
137
|
+
this,
|
|
138
|
+
&this.core,
|
|
139
|
+
|core| core.select_epsilon_greedy(epsilon, draws),
|
|
140
|
+
|outcome| Self::selected(ruby, class, outcome),
|
|
141
|
+
)
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/// The core answers `Ok(())`; Ruby names the honoured effect with `done`.
|
|
145
|
+
fn settled(ruby: &Ruby, outcome: Result<(), Refusal>, done: &'static str) -> Value {
|
|
146
|
+
Self::answer(ruby, outcome, |()| symbol(ruby, done).as_value())
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
fn reward(ruby: &Ruby, this: Obj<Self>, handle: Value, reward: Value) -> Result<Value, Error> {
|
|
150
|
+
this.check_frozen()?;
|
|
151
|
+
let handle = convert::ticket(ruby, handle)?;
|
|
152
|
+
let reward = integer(reward, "reward")?;
|
|
153
|
+
let outcome = this.core.borrow_mut().reward(handle.0, reward);
|
|
154
|
+
Ok(Self::settled(ruby, outcome, "rewarded"))
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
fn abandon(ruby: &Ruby, this: Obj<Self>, handle: Value) -> Result<Value, Error> {
|
|
158
|
+
this.check_frozen()?;
|
|
159
|
+
let handle = convert::ticket(ruby, handle)?;
|
|
160
|
+
let outcome = this.core.borrow_mut().abandon(handle.0);
|
|
161
|
+
Ok(Self::settled(ruby, outcome, "abandoned"))
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
fn revoke_before(ruby: &Ruby, this: Obj<Self>, serial: Value) -> Result<Value, Error> {
|
|
165
|
+
this.check_frozen()?;
|
|
166
|
+
let serial = integer(serial, "serial")?;
|
|
167
|
+
let outcome = this.core.borrow_mut().revoke_before(serial);
|
|
168
|
+
Ok(Self::voided(ruby, outcome))
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
fn revoke_all(this: Obj<Self>) -> Result<usize, Error> {
|
|
172
|
+
this.check_frozen()?;
|
|
173
|
+
Ok(this.core.borrow_mut().revoke_all())
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
fn voided(ruby: &Ruby, outcome: Result<usize, Refusal>) -> Value {
|
|
177
|
+
Self::answer(ruby, outcome, |voided| ruby.into_value(voided))
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
fn reset(ruby: &Ruby, this: Obj<Self>, arm: Value) -> Result<Value, Error> {
|
|
181
|
+
this.check_frozen()?;
|
|
182
|
+
let arm = integer(arm, "arm")?;
|
|
183
|
+
let outcome = this.core.borrow_mut().reset(arm);
|
|
184
|
+
Ok(Self::voided(ruby, outcome))
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
fn reset_all(ruby: &Ruby, this: Obj<Self>) -> Result<Value, Error> {
|
|
188
|
+
this.check_frozen()?;
|
|
189
|
+
let outcome = this.core.borrow_mut().reset_all();
|
|
190
|
+
Ok(Self::voided(ruby, outcome))
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
fn decay(ruby: &Ruby, this: Obj<Self>, arm: Value, keep: Value) -> Result<Value, Error> {
|
|
194
|
+
this.check_frozen()?;
|
|
195
|
+
let arm = integer(arm, "arm")?;
|
|
196
|
+
let keep = convert::ratio(ruby, keep)?;
|
|
197
|
+
let outcome = this.core.borrow_mut().decay(arm, keep);
|
|
198
|
+
Ok(Self::settled(ruby, outcome, "decayed"))
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
fn decay_all(ruby: &Ruby, this: Obj<Self>, keep: Value) -> Result<Symbol, Error> {
|
|
202
|
+
this.check_frozen()?;
|
|
203
|
+
let keep = convert::ratio(ruby, keep)?;
|
|
204
|
+
this.core.borrow_mut().decay_all(keep);
|
|
205
|
+
Ok(symbol(ruby, "decayed"))
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
fn open(ruby: &Ruby, this: Obj<Self>, arm: Value) -> Result<Value, Error> {
|
|
209
|
+
this.check_frozen()?;
|
|
210
|
+
let arm = integer(arm, "arm")?;
|
|
211
|
+
let outcome = this.core.borrow_mut().open(arm);
|
|
212
|
+
Ok(Self::answer(ruby, outcome, |opening| {
|
|
213
|
+
symbol(ruby, convert::opening(opening)).as_value()
|
|
214
|
+
}))
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
fn close(ruby: &Ruby, this: Obj<Self>, arm: Value) -> Result<Value, Error> {
|
|
218
|
+
this.check_frozen()?;
|
|
219
|
+
let arm = integer(arm, "arm")?;
|
|
220
|
+
let outcome = this.core.borrow_mut().close(arm);
|
|
221
|
+
Ok(Self::answer(ruby, outcome, |closing| {
|
|
222
|
+
symbol(ruby, convert::closing(closing)).as_value()
|
|
223
|
+
}))
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
fn stats(ruby: &Ruby, this: &Self, arm: Value) -> Result<Option<Value>, Error> {
|
|
227
|
+
let arm = integer(arm, "arm")?;
|
|
228
|
+
let stats = this.core.borrow().stats(arm);
|
|
229
|
+
stats
|
|
230
|
+
.map(|stats| convert::stats_value(ruby, stats))
|
|
231
|
+
.transpose()
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
fn ucb1_index_q56(&self, arm: Value) -> Result<Option<u64>, Error> {
|
|
235
|
+
let arm = integer(arm, "arm")?;
|
|
236
|
+
Ok(self.core.borrow().ucb1_index_q56(arm))
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
fn outstanding(&self) -> usize {
|
|
240
|
+
self.core.borrow().outstanding()
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
fn next_serial(&self) -> Option<u64> {
|
|
244
|
+
self.core.borrow().next_serial()
|
|
245
|
+
}
|
|
246
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'bandit_machines/version'
|
|
4
|
+
|
|
5
|
+
# A bounded multi-armed bandit. Every value mirrors the Rust core's type of
|
|
6
|
+
# the same name, field for field; each checks itself natively when it is built.
|
|
7
|
+
module BanditMachines
|
|
8
|
+
# Reward range, warming prior and tie rule shared by every arm:
|
|
9
|
+
# `0 < max_reward`, `prior <= max_reward`, both in 0..2**32-1, and
|
|
10
|
+
# `tie_break` one of :lowest_index, :highest_index, :least_tried, :draw.
|
|
11
|
+
Config = Data.define(:max_reward, :prior, :tie_break) do
|
|
12
|
+
def initialize(max_reward:, prior:, tie_break:)
|
|
13
|
+
super
|
|
14
|
+
__validate
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# A fraction in 0..1: `numerator <= denominator`, `denominator > 0`, both in
|
|
19
|
+
# 0..2**32-1. `Ratio::ZERO` and `Ratio::ONE` are the core's constants.
|
|
20
|
+
Ratio = Data.define(:numerator, :denominator) do
|
|
21
|
+
def initialize(numerator:, denominator:)
|
|
22
|
+
super
|
|
23
|
+
__validate
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# The two uniform draws one epsilon-greedy selection may consume, each in
|
|
28
|
+
# 0..2**64-1: `gate` decides explore versus exploit, `pick` chooses the arm.
|
|
29
|
+
Draws = Data.define(:gate, :pick) do
|
|
30
|
+
def initialize(gate:, pick:)
|
|
31
|
+
super
|
|
32
|
+
__validate
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# A selected arm's ticket and the rule that picked it: `ticket` a Ticket,
|
|
37
|
+
# `reason` one of :cold_start, :explore, :exploit, :upper_bound.
|
|
38
|
+
Selection = Data.define(:ticket, :reason) do
|
|
39
|
+
def initialize(ticket:, reason:)
|
|
40
|
+
super
|
|
41
|
+
__validate
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def arm = ticket.arm
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# Snapshot of one arm: `open` true or false, every count in 0..2**64-1.
|
|
48
|
+
ArmStats = Data.define(:open, :generation, :rewarded, :reward_sum, :pending) do
|
|
49
|
+
def initialize(open:, generation:, rewarded:, reward_sum:, pending:)
|
|
50
|
+
super
|
|
51
|
+
__validate
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def tries = [rewarded + pending, (2**64) - 1].min
|
|
55
|
+
end
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# Native is required: no algorithm fallback. It adds the checks to the values
|
|
59
|
+
# above, so they must exist first.
|
|
60
|
+
require 'bandit_machines_native/bandit_machines_native'
|
|
61
|
+
|
|
62
|
+
module BanditMachines
|
|
63
|
+
# The values are sealed. `initialize` is where each validates, and a
|
|
64
|
+
# subclass could override it, or `allocate` build an instance that never ran
|
|
65
|
+
# it: subclassing raises TypeError and `allocate` is gone. Sealing stops
|
|
66
|
+
# accidents, not reflection (a named subclass's constant is bound before
|
|
67
|
+
# `inherited` raises; `Marshal.load` skips `initialize`), so the native side
|
|
68
|
+
# is the authority: a value it reads must be exactly its class, and every
|
|
69
|
+
# field is converted again through the core's constructors.
|
|
70
|
+
[Config, Ratio, Draws, Selection, ArmStats].each do |value|
|
|
71
|
+
value.singleton_class.undef_method(:allocate)
|
|
72
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
73
|
+
end
|
|
74
|
+
end
|