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.
@@ -1,4 +1,4 @@
1
1
  # frozen_string_literal: true
2
2
  module FeedbackMachines
3
- VERSION = '0.1.4'
3
+ VERSION = '0.6.1'
4
4
  end
@@ -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
- class Pid
7
- def self.new(p:, min:, max:, i: 0.0, d: 0.0) = _new(p, i, d, min, max)
8
- private_class_method :_new
9
- def step(error:, elapsed:) = _step(error, elapsed)
10
- private :_step
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
- class Hysteresis
14
- def self.new(min:, max:) = _new(min, max)
15
- private_class_method :_new
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
@@ -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
- def self.new: (p: Float, min: Float, max: Float, ?i: Float, ?d: Float) -> instance
5
- def step: (error: Float, elapsed: Float) -> Float?
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
- def self.new: (min: Float, max: Float) -> instance
9
- def observe: (Float) -> (:low | :high)?
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
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