feedback_machines 0.1.4 → 0.6.1
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 +4 -4
- data/CHANGELOG.md +69 -0
- data/Cargo.lock +307 -0
- data/Cargo.toml +2 -0
- data/README.md +90 -33
- data/ext/feedback_machines_native/core/CHANGELOG.md +44 -0
- data/ext/feedback_machines_native/core/Cargo.toml +4 -2
- data/ext/feedback_machines_native/core/README.md +50 -3
- data/ext/feedback_machines_native/core/src/lib.rs +172 -18
- data/ext/feedback_machines_native/ffi/Cargo.toml +2 -1
- data/ext/feedback_machines_native/ffi/src/bindings.rs +199 -36
- data/lib/feedback_machines/version.rb +1 -1
- data/lib/feedback_machines.rb +38 -8
- data/sig/feedback_machines.rbs +92 -4
- metadata +2 -1
data/lib/feedback_machines.rb
CHANGED
|
@@ -1,17 +1,47 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
require_relative 'feedback_machines/version'
|
|
3
|
+
|
|
4
|
+
module FeedbackMachines
|
|
5
|
+
# The core's `Gains`: proportional, integral and derivative coefficients.
|
|
6
|
+
# Like `Gains::new`, it holds only finite, nonnegative values: anything else
|
|
7
|
+
# raises RangeError (TypeError for a non-number). Stored as Floats.
|
|
8
|
+
Gains = Data.define(:p, :i, :d) do
|
|
9
|
+
def initialize(p:, i:, d:)
|
|
10
|
+
p, i, d = FeedbackMachines.__send__(:__gains, p, i, d)
|
|
11
|
+
super
|
|
12
|
+
end
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
# The core's `Limits`: a finite range with min < max, as `Limits::new`
|
|
16
|
+
# requires: anything else raises RangeError (TypeError for a non-number).
|
|
17
|
+
# Stored as Floats. Output limits for a Pid, thresholds for a Hysteresis.
|
|
18
|
+
Limits = Data.define(:min, :max) do
|
|
19
|
+
def initialize(min:, max:)
|
|
20
|
+
min, max = FeedbackMachines.__send__(:__limits, min, max)
|
|
21
|
+
super
|
|
22
|
+
end
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# Native is required: there is no pure-Ruby fallback. It validates and builds
|
|
27
|
+
# the Data values above.
|
|
3
28
|
require 'feedback_machines_native/feedback_machines_native'
|
|
4
29
|
|
|
5
30
|
module FeedbackMachines
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
31
|
+
private_class_method :__gains, :__limits
|
|
32
|
+
|
|
33
|
+
# The values are final. `initialize` is where each validates, and a subclass
|
|
34
|
+
# could override it, or `allocate` build an instance that never ran it:
|
|
35
|
+
# subclassing raises TypeError and `allocate` is gone. This stops accidents,
|
|
36
|
+
# not reflection, so the binding also checks every value it reads.
|
|
37
|
+
[Gains, Limits].each do |value|
|
|
38
|
+
value.singleton_class.undef_method(:allocate)
|
|
39
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
11
40
|
end
|
|
12
41
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
42
|
+
# The controllers wrap native state and have no allocator: a subclass's
|
|
43
|
+
# `new` would build the base class anyway, so subclassing raises too.
|
|
44
|
+
[Pid, Hysteresis].each do |controller|
|
|
45
|
+
controller.define_singleton_method(:inherited) { |_| raise TypeError, "#{controller} cannot be subclassed" }
|
|
16
46
|
end
|
|
17
47
|
end
|
data/sig/feedback_machines.rbs
CHANGED
|
@@ -1,11 +1,99 @@
|
|
|
1
1
|
module FeedbackMachines
|
|
2
2
|
VERSION: String
|
|
3
|
+
|
|
4
|
+
# The core's `Refusal`: the call was not honoured and changed nothing.
|
|
5
|
+
# :not_finite, the sample is NaN or infinite.
|
|
6
|
+
# :invalid_duration, the elapsed time is zero.
|
|
7
|
+
# :overflow, the sample is finite but a term of the calculation is not.
|
|
8
|
+
type refusal = :not_finite | :invalid_duration | :overflow
|
|
9
|
+
|
|
10
|
+
# The core's `Band`.
|
|
11
|
+
type band = :low | :high
|
|
12
|
+
|
|
13
|
+
# The core's `Gains`. `new` mirrors `Gains::new(p, i, d)`: it raises
|
|
14
|
+
# RangeError unless every gain is finite and nonnegative, TypeError for
|
|
15
|
+
# anything but a Float or Integer (a Rational included). The fields are
|
|
16
|
+
# stored as Floats. Sealed (subclassing raises TypeError, no `allocate`);
|
|
17
|
+
# the binding reads only instances of exactly this class and re-checks
|
|
18
|
+
# their fields, so a forged value raises.
|
|
19
|
+
class Gains < Data
|
|
20
|
+
attr_reader p: Float
|
|
21
|
+
attr_reader i: Float
|
|
22
|
+
attr_reader d: Float
|
|
23
|
+
def self.new: ((Float | Integer) p, (Float | Integer) i, (Float | Integer) d) -> Gains
|
|
24
|
+
| (p: (Float | Integer), i: (Float | Integer), d: (Float | Integer)) -> Gains
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# The core's `Limits`. `new` mirrors `Limits::new(min, max)`: it raises
|
|
28
|
+
# RangeError unless both are finite and min < max, TypeError for anything
|
|
29
|
+
# but a Float or Integer (a Rational included). The fields are stored as
|
|
30
|
+
# Floats. Sealed and re-checked by the binding like Gains.
|
|
31
|
+
class Limits < Data
|
|
32
|
+
attr_reader min: Float
|
|
33
|
+
attr_reader max: Float
|
|
34
|
+
def self.new: ((Float | Integer) min, (Float | Integer) max) -> Limits
|
|
35
|
+
| (min: (Float | Integer), max: (Float | Integer)) -> Limits
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
# The core's `Pid`. Sealed: subclassing raises TypeError, no `allocate`.
|
|
3
39
|
class Pid
|
|
4
|
-
|
|
5
|
-
|
|
40
|
+
# The core's `Pid::new(gains, limits)`. Raises TypeError unless given
|
|
41
|
+
# instances of exactly Gains and Limits, RangeError if their fields fail
|
|
42
|
+
# the core's constructors.
|
|
43
|
+
def self.new: (Gains gains, Limits limits) -> Pid
|
|
44
|
+
|
|
45
|
+
# The core's `Pid::restored(gains, limits, integral, previous_error)`:
|
|
46
|
+
# resumes a controller saved through its readers. Raises TypeError for
|
|
47
|
+
# gains or limits that are not exactly Gains and Limits, or an integral
|
|
48
|
+
# or previous_error that is not a Float or Integer (previous_error may be
|
|
49
|
+
# nil), RangeError for invalid gains or limits or a non-finite integral or
|
|
50
|
+
# previous_error.
|
|
51
|
+
def self.restored: (Gains gains, Limits limits, (Float | Integer) integral, (Float | Integer)? previous_error) -> Pid
|
|
52
|
+
def gains: () -> Gains
|
|
53
|
+
def limits: () -> Limits
|
|
54
|
+
|
|
55
|
+
# The accumulated error-seconds the integral gain multiplies. A query.
|
|
56
|
+
def integral: () -> Float
|
|
57
|
+
|
|
58
|
+
# The error of the previous honoured sample, nil before the first. A query.
|
|
59
|
+
def previous_error: () -> Float?
|
|
60
|
+
|
|
61
|
+
# The core's `Pid::step(error, elapsed)`. `elapsed` is the span since the
|
|
62
|
+
# previous sample in Integer nanoseconds. Honoured: the output, a Float
|
|
63
|
+
# within the limits. Refused: :not_finite (error is NaN or infinite),
|
|
64
|
+
# :invalid_duration (elapsed is zero) or :overflow; the controller is
|
|
65
|
+
# unchanged. Never nil. Raises TypeError for a non-Integer elapsed or a
|
|
66
|
+
# error that is not a Float or Integer, RangeError for an elapsed outside 0..2**64-1,
|
|
67
|
+
# FrozenError on a frozen controller, all before the controller is
|
|
68
|
+
# stepped. Records no clock: `elapsed` is a span, not an instant.
|
|
69
|
+
def step: ((Float | Integer) error, Integer elapsed) -> (Float | refusal)
|
|
6
70
|
end
|
|
71
|
+
|
|
72
|
+
# The core's `Hysteresis`. Sealed like Pid.
|
|
7
73
|
class Hysteresis
|
|
8
|
-
|
|
9
|
-
|
|
74
|
+
# The core's `Hysteresis::new(limits)`: starts :low. Raises TypeError
|
|
75
|
+
# unless given an instance of exactly Limits, RangeError if its fields
|
|
76
|
+
# fail the core's constructor.
|
|
77
|
+
def self.new: (Limits limits) -> Hysteresis
|
|
78
|
+
|
|
79
|
+
# The core's `Hysteresis::restored(limits, state)`: resumes a band on
|
|
80
|
+
# `state`. Raises like `new` for the limits, TypeError for a non-Symbol
|
|
81
|
+
# state, RangeError for a Symbol other than :low or :high.
|
|
82
|
+
def self.restored: (Limits limits, band state) -> Hysteresis
|
|
83
|
+
def limits: () -> Limits
|
|
84
|
+
|
|
85
|
+
# The side the band is on now. A query.
|
|
86
|
+
def state: () -> band
|
|
87
|
+
|
|
88
|
+
# The core's `Hysteresis::observe(value)`. Honoured: the side the band is
|
|
89
|
+
# on after the measurement. Refused: :not_finite, and the band keeps its
|
|
90
|
+
# side. Never nil. Raises TypeError for anything but a Float or Integer, FrozenError on a
|
|
91
|
+
# frozen band, before the band moves. Records no clock.
|
|
92
|
+
def observe: ((Float | Integer) value) -> (band | :not_finite)
|
|
10
93
|
end
|
|
94
|
+
|
|
95
|
+
# Private native hooks the Data values validate through: the checked
|
|
96
|
+
# fields, converted to Floats.
|
|
97
|
+
private def self.__gains: ((Float | Integer) p, (Float | Integer) i, (Float | Integer) d) -> [Float, Float, Float]
|
|
98
|
+
private def self.__limits: ((Float | Integer) min, (Float | Integer) max) -> [Float, Float]
|
|
11
99
|
end
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: feedback_machines
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1
|
|
4
|
+
version: 0.6.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Abdelkader Boudih
|
|
@@ -39,6 +39,7 @@ extensions:
|
|
|
39
39
|
extra_rdoc_files: []
|
|
40
40
|
files:
|
|
41
41
|
- CHANGELOG.md
|
|
42
|
+
- Cargo.lock
|
|
42
43
|
- Cargo.toml
|
|
43
44
|
- LICENSE.txt
|
|
44
45
|
- README.md
|