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,157 @@
|
|
|
1
|
+
module BanditMachines
|
|
2
|
+
VERSION: String
|
|
3
|
+
|
|
4
|
+
type tie_break = :lowest_index | :highest_index | :least_tried | :draw
|
|
5
|
+
type reason = :cold_start | :explore | :exploit | :upper_bound
|
|
6
|
+
# Every symbol that means "this call was not honoured and changed nothing":
|
|
7
|
+
# one per variant of the core's `Refusal`. Each method below lists exactly
|
|
8
|
+
# the ones it can answer.
|
|
9
|
+
type refusal = :unknown_arm | :no_open_arm | :tickets_full | :exhausted | :stale_ticket | :unknown_ticket
|
|
10
|
+
| :reward_out_of_range | :saturated
|
|
11
|
+
|
|
12
|
+
# `0 < max_reward`, `prior <= max_reward`, both in 0..2**32-1; anything else
|
|
13
|
+
# raises TypeError or RangeError, and so does an unknown tie_break
|
|
14
|
+
# (TypeError for a non-Symbol, RangeError for an unknown Symbol).
|
|
15
|
+
class Config < Data
|
|
16
|
+
attr_reader max_reward: Integer
|
|
17
|
+
attr_reader prior: Integer
|
|
18
|
+
attr_reader tie_break: tie_break
|
|
19
|
+
def self.new: (Integer max_reward, Integer prior, tie_break tie_break) -> Config
|
|
20
|
+
| (max_reward: Integer, prior: Integer, tie_break: tie_break) -> Config
|
|
21
|
+
# Native: re-checks every field through the core constructor; raises
|
|
22
|
+
# TypeError or RangeError, nil when valid.
|
|
23
|
+
private def __validate: () -> nil
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# `numerator <= denominator`, `denominator > 0`, both in 0..2**32-1.
|
|
27
|
+
class Ratio < Data
|
|
28
|
+
ZERO: Ratio
|
|
29
|
+
ONE: Ratio
|
|
30
|
+
attr_reader numerator: Integer
|
|
31
|
+
attr_reader denominator: Integer
|
|
32
|
+
def self.new: (Integer numerator, Integer denominator) -> Ratio
|
|
33
|
+
| (numerator: Integer, denominator: Integer) -> Ratio
|
|
34
|
+
# Native: re-checks every field through the core constructor; raises
|
|
35
|
+
# TypeError or RangeError, nil when valid.
|
|
36
|
+
private def __validate: () -> nil
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
# Two uniform draws, each in 0..2**64-1.
|
|
40
|
+
class Draws < Data
|
|
41
|
+
attr_reader gate: Integer
|
|
42
|
+
attr_reader pick: Integer
|
|
43
|
+
def self.new: (Integer gate, Integer pick) -> Draws
|
|
44
|
+
| (gate: Integer, pick: Integer) -> Draws
|
|
45
|
+
# Native: re-checks every field through the core constructor; raises
|
|
46
|
+
# TypeError or RangeError, nil when valid.
|
|
47
|
+
private def __validate: () -> nil
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# Mirrors the core's `Ticket`. Opaque; it cannot be built or copied by hand.
|
|
51
|
+
# Only the bandit that issued it honours it.
|
|
52
|
+
class Ticket
|
|
53
|
+
def arm: () -> Integer
|
|
54
|
+
def generation: () -> Integer
|
|
55
|
+
# The scoped id: the issuing bandit's scope in the top 16 bits, the
|
|
56
|
+
# position in its selection order (from one) in the low 48.
|
|
57
|
+
def serial: () -> Integer
|
|
58
|
+
# The scope of the bandit that issued it, 0..65535.
|
|
59
|
+
def scope: () -> Integer
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
# `ticket` a Ticket and `reason` a Symbol (TypeError otherwise); an unknown
|
|
63
|
+
# reason Symbol raises RangeError.
|
|
64
|
+
class Selection < Data
|
|
65
|
+
attr_reader ticket: Ticket
|
|
66
|
+
attr_reader reason: reason
|
|
67
|
+
def self.new: (Ticket ticket, reason reason) -> Selection
|
|
68
|
+
| (ticket: Ticket, reason: reason) -> Selection
|
|
69
|
+
def arm: () -> Integer
|
|
70
|
+
# Native: re-checks every field through the core constructor; raises
|
|
71
|
+
# TypeError or RangeError, nil when valid.
|
|
72
|
+
private def __validate: () -> nil
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
# `open` true or false (TypeError otherwise), every count an Integer
|
|
76
|
+
# (TypeError otherwise) in 0..2**64-1 (RangeError otherwise).
|
|
77
|
+
class ArmStats < Data
|
|
78
|
+
attr_reader open: bool
|
|
79
|
+
attr_reader generation: Integer
|
|
80
|
+
attr_reader rewarded: Integer
|
|
81
|
+
attr_reader reward_sum: Integer
|
|
82
|
+
attr_reader pending: Integer
|
|
83
|
+
def self.new: (bool open, Integer generation, Integer rewarded, Integer reward_sum, Integer pending) -> ArmStats
|
|
84
|
+
| (open: bool, generation: Integer, rewarded: Integer, reward_sum: Integer, pending: Integer) -> ArmStats
|
|
85
|
+
def tries: () -> Integer
|
|
86
|
+
# Native: re-checks every field through the core constructor; raises
|
|
87
|
+
# TypeError or RangeError, nil when valid.
|
|
88
|
+
private def __validate: () -> nil
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
# The core's `math` module: unsigned Q8.56 fixed point, integers in and out.
|
|
92
|
+
module Math
|
|
93
|
+
FRACTION_BITS: Integer
|
|
94
|
+
ONE: Integer
|
|
95
|
+
def self.log2_q56: (Integer value) -> Integer
|
|
96
|
+
def self.ln_q56: (Integer value) -> Integer
|
|
97
|
+
def self.bonus_q56: (Integer total, Integer tries) -> Integer
|
|
98
|
+
def self.mean_q56: (Integer sum, Integer count, Integer range) -> Integer
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# An arm index is any Integer in 0..2**64-1. One that names no arm
|
|
102
|
+
# (Bandit::ARMS or above) is answered, not raised: :unknown_arm from the
|
|
103
|
+
# mutating methods, nil from `stats` and `ucb1_index_q56`.
|
|
104
|
+
class Bandit
|
|
105
|
+
# The core's `Bandit::ARMS`: compiled number of arms.
|
|
106
|
+
ARMS: Integer
|
|
107
|
+
# The core's `Bandit::TICKETS`: compiled number of outstanding tickets.
|
|
108
|
+
TICKETS: Integer
|
|
109
|
+
# Scope zero.
|
|
110
|
+
def self.new: (Config config) -> Bandit
|
|
111
|
+
# `scope` is an Integer in 0..65535: TypeError otherwise, RangeError
|
|
112
|
+
# outside the range.
|
|
113
|
+
def self.with_scope: (Config config, Integer scope) -> Bandit
|
|
114
|
+
# Continues `scope` after a restart from a saved `issued` count. Restores
|
|
115
|
+
# only the serial sequence: every arm is closed and nothing is outstanding.
|
|
116
|
+
# RangeError when `issued` is above 2**48 - 1.
|
|
117
|
+
def self.resumed: (Config config, Integer scope, Integer issued) -> Bandit
|
|
118
|
+
def config: () -> Config
|
|
119
|
+
# The scope carried by every Ticket this bandit issues.
|
|
120
|
+
def scope: () -> Integer
|
|
121
|
+
# Serials issued in this scope so far: the count to save for `resumed`.
|
|
122
|
+
def issued: () -> Integer
|
|
123
|
+
def outstanding: () -> Integer
|
|
124
|
+
# nil once every serial of the scope has been issued.
|
|
125
|
+
def next_serial: () -> Integer?
|
|
126
|
+
def stats: (Integer arm) -> ArmStats?
|
|
127
|
+
# Honoured: :opened, or the repeat :already_open. Refused: :unknown_arm.
|
|
128
|
+
def open: (Integer arm) -> (:opened | :already_open | :unknown_arm)
|
|
129
|
+
# Honoured: :closed, or the repeat :already_closed. Refused: :unknown_arm.
|
|
130
|
+
def close: (Integer arm) -> (:closed | :already_closed | :unknown_arm)
|
|
131
|
+
# Honoured: a Selection. Refused: :no_open_arm, :tickets_full, :exhausted.
|
|
132
|
+
def select_ucb1: (Integer pick) -> (Selection | :no_open_arm | :tickets_full | :exhausted)
|
|
133
|
+
def select_epsilon_greedy: (Ratio epsilon, Draws draws) -> (Selection | :no_open_arm | :tickets_full | :exhausted)
|
|
134
|
+
# nil for an unknown, closed or cold arm.
|
|
135
|
+
def ucb1_index_q56: (Integer arm) -> Integer?
|
|
136
|
+
# Honoured: :rewarded. Refused: :stale_ticket, :unknown_ticket (a Ticket
|
|
137
|
+
# from a bandit in another scope included), :reward_out_of_range,
|
|
138
|
+
# :saturated.
|
|
139
|
+
def reward: (Ticket ticket, Integer reward) -> (:rewarded | :stale_ticket | :unknown_ticket | :reward_out_of_range | :saturated)
|
|
140
|
+
# Honoured: :abandoned. Refused: :stale_ticket, :unknown_ticket.
|
|
141
|
+
def abandon: (Ticket ticket) -> (:abandoned | :stale_ticket | :unknown_ticket)
|
|
142
|
+
# Honoured: the number of tickets revoked. Refused: :unknown_ticket, for a
|
|
143
|
+
# serial of another scope.
|
|
144
|
+
def revoke_before: (Integer serial) -> (Integer | :unknown_ticket)
|
|
145
|
+
# The number of tickets revoked: every outstanding one. Never refuses;
|
|
146
|
+
# arm statistics and generations are kept.
|
|
147
|
+
def revoke_all: () -> Integer
|
|
148
|
+
# Honoured: the number of tickets voided. Refused: :unknown_arm, :exhausted.
|
|
149
|
+
def reset: (Integer arm) -> (Integer | :unknown_arm | :exhausted)
|
|
150
|
+
# Honoured: the number of tickets voided. Refused: :exhausted.
|
|
151
|
+
def reset_all: () -> (Integer | :exhausted)
|
|
152
|
+
# Honoured: :decayed. Refused: :unknown_arm.
|
|
153
|
+
def decay: (Integer arm, Ratio keep) -> (:decayed | :unknown_arm)
|
|
154
|
+
# Always honoured.
|
|
155
|
+
def decay_all: (Ratio keep) -> :decayed
|
|
156
|
+
end
|
|
157
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: bandit_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.7.2
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: rb_sys
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - "~>"
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: '0.9'
|
|
19
|
+
- - ">="
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: 0.9.130
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - "~>"
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: '0.9'
|
|
29
|
+
- - ">="
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: 0.9.130
|
|
32
|
+
description: UCB1 and epsilon-greedy arm selection with ticketed rewards; not an experiment
|
|
33
|
+
platform.
|
|
34
|
+
email:
|
|
35
|
+
- oss@seuros.com
|
|
36
|
+
executables: []
|
|
37
|
+
extensions:
|
|
38
|
+
- ext/bandit_machines_native/extconf.rb
|
|
39
|
+
extra_rdoc_files: []
|
|
40
|
+
files:
|
|
41
|
+
- CHANGELOG.md
|
|
42
|
+
- Cargo.lock
|
|
43
|
+
- Cargo.toml
|
|
44
|
+
- LICENSE.txt
|
|
45
|
+
- README.md
|
|
46
|
+
- ext/bandit_machines_native/core/CHANGELOG.md
|
|
47
|
+
- ext/bandit_machines_native/core/Cargo.toml
|
|
48
|
+
- ext/bandit_machines_native/core/README.md
|
|
49
|
+
- ext/bandit_machines_native/core/src/bandit.rs
|
|
50
|
+
- ext/bandit_machines_native/core/src/lib.rs
|
|
51
|
+
- ext/bandit_machines_native/core/src/math.rs
|
|
52
|
+
- ext/bandit_machines_native/core/src/pick.rs
|
|
53
|
+
- ext/bandit_machines_native/extconf.rb
|
|
54
|
+
- ext/bandit_machines_native/ffi/Cargo.toml
|
|
55
|
+
- ext/bandit_machines_native/ffi/extconf.rb
|
|
56
|
+
- ext/bandit_machines_native/ffi/src/convert.rs
|
|
57
|
+
- ext/bandit_machines_native/ffi/src/init.rs
|
|
58
|
+
- ext/bandit_machines_native/ffi/src/lib.rs
|
|
59
|
+
- lib/bandit_machines.rb
|
|
60
|
+
- lib/bandit_machines/version.rb
|
|
61
|
+
- sig/bandit_machines.rbs
|
|
62
|
+
homepage: https://github.com/seuros/bandit_machines
|
|
63
|
+
licenses:
|
|
64
|
+
- MIT
|
|
65
|
+
metadata:
|
|
66
|
+
source_code_uri: https://github.com/seuros/bandit_machines
|
|
67
|
+
rubygems_mfa_required: 'true'
|
|
68
|
+
cargo_crate_name: bandit_machines_native
|
|
69
|
+
cargo_manifest_path: ext/bandit_machines_native/ffi/Cargo.toml
|
|
70
|
+
rdoc_options: []
|
|
71
|
+
require_paths:
|
|
72
|
+
- lib
|
|
73
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
74
|
+
requirements:
|
|
75
|
+
- - ">="
|
|
76
|
+
- !ruby/object:Gem::Version
|
|
77
|
+
version: 4.0.0
|
|
78
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
79
|
+
requirements:
|
|
80
|
+
- - ">="
|
|
81
|
+
- !ruby/object:Gem::Version
|
|
82
|
+
version: '0'
|
|
83
|
+
requirements: []
|
|
84
|
+
rubygems_version: 4.0.20
|
|
85
|
+
specification_version: 4
|
|
86
|
+
summary: Bounded multi-armed bandit policies with a native Rust core
|
|
87
|
+
test_files: []
|