runmat_runtime/builtins/control/
feedback.rs

1//! MATLAB-compatible SISO `feedback` interconnection for transfer functions.
2
3use runmat_builtins::{
4    BuiltinCompletionPolicy, BuiltinDescriptor, BuiltinErrorDescriptor, BuiltinOutputMode,
5    BuiltinParamArity, BuiltinParamDescriptor, BuiltinParamType, BuiltinSignatureDescriptor, Value,
6};
7use runmat_macros::runtime_builtin;
8
9use crate::builtins::common::spec::{
10    BroadcastSemantics, BuiltinFusionSpec, BuiltinGpuSpec, ConstantStrategy, GpuOpKind,
11    ReductionNaN, ResidencyPolicy, ShapeRequirements,
12};
13use crate::builtins::control::tf_model::{scalar_f64, two_models_ordered};
14use crate::builtins::control::type_resolvers::feedback_type;
15use crate::{BuiltinResult, RuntimeError};
16
17const BUILTIN_NAME: &str = "feedback";
18
19const FEEDBACK_OUTPUT: [BuiltinParamDescriptor; 1] = [BuiltinParamDescriptor {
20    name: "sys",
21    ty: BuiltinParamType::Any,
22    arity: BuiltinParamArity::Required,
23    default: None,
24    description: "Closed-loop SISO transfer-function object.",
25}];
26const FEEDBACK_PARAM_SYS1: BuiltinParamDescriptor = BuiltinParamDescriptor {
27    name: "sys1",
28    ty: BuiltinParamType::Any,
29    arity: BuiltinParamArity::Required,
30    default: None,
31    description: "Forward-path SISO transfer-function model.",
32};
33const FEEDBACK_PARAM_SYS2: BuiltinParamDescriptor = BuiltinParamDescriptor {
34    name: "sys2",
35    ty: BuiltinParamType::Any,
36    arity: BuiltinParamArity::Optional,
37    default: Some("1"),
38    description: "Feedback-path SISO transfer function or scalar gain.",
39};
40const FEEDBACK_PARAM_SIGN: BuiltinParamDescriptor = BuiltinParamDescriptor {
41    name: "sign",
42    ty: BuiltinParamType::NumericScalar,
43    arity: BuiltinParamArity::Optional,
44    default: Some("-1"),
45    description: "-1 for negative feedback or +1 for positive feedback.",
46};
47const FEEDBACK_INPUT_SYS: [BuiltinParamDescriptor; 1] = [FEEDBACK_PARAM_SYS1];
48const FEEDBACK_INPUT_SYS_OTHER: [BuiltinParamDescriptor; 2] =
49    [FEEDBACK_PARAM_SYS1, FEEDBACK_PARAM_SYS2];
50const FEEDBACK_INPUT_SYS_OTHER_SIGN: [BuiltinParamDescriptor; 3] = [
51    FEEDBACK_PARAM_SYS1,
52    FEEDBACK_PARAM_SYS2,
53    FEEDBACK_PARAM_SIGN,
54];
55const FEEDBACK_SIGNATURES: [BuiltinSignatureDescriptor; 3] = [
56    BuiltinSignatureDescriptor {
57        label: "sys = feedback(sys1)",
58        inputs: &FEEDBACK_INPUT_SYS,
59        outputs: &FEEDBACK_OUTPUT,
60    },
61    BuiltinSignatureDescriptor {
62        label: "sys = feedback(sys1, sys2)",
63        inputs: &FEEDBACK_INPUT_SYS_OTHER,
64        outputs: &FEEDBACK_OUTPUT,
65    },
66    BuiltinSignatureDescriptor {
67        label: "sys = feedback(sys1, sys2, sign)",
68        inputs: &FEEDBACK_INPUT_SYS_OTHER_SIGN,
69        outputs: &FEEDBACK_OUTPUT,
70    },
71];
72const FEEDBACK_ERRORS: [BuiltinErrorDescriptor; 5] = [
73    BuiltinErrorDescriptor {
74        code: "RM.FEEDBACK.INVALID_ARGUMENT",
75        identifier: Some("RunMat:feedback:InvalidArgument"),
76        when: "Inputs do not match supported feedback invocation forms.",
77        message: "feedback: invalid argument",
78    },
79    BuiltinErrorDescriptor {
80        code: "RM.FEEDBACK.INVALID_MODEL",
81        identifier: Some("RunMat:feedback:InvalidModel"),
82        when: "Input systems are not supported SISO transfer-function models.",
83        message: "feedback: invalid model",
84    },
85    BuiltinErrorDescriptor {
86        code: "RM.FEEDBACK.INVALID_SIGN",
87        identifier: Some("RunMat:feedback:InvalidSign"),
88        when: "Feedback sign is not -1 or +1.",
89        message: "feedback: sign must be -1 or +1",
90    },
91    BuiltinErrorDescriptor {
92        code: "RM.FEEDBACK.UNSUPPORTED_MODEL",
93        identifier: Some("RunMat:feedback:UnsupportedModel"),
94        when: "A supported-looking model uses unsupported delays or incompatible sample times.",
95        message: "feedback: unsupported model",
96    },
97    BuiltinErrorDescriptor {
98        code: "RM.FEEDBACK.INTERNAL",
99        identifier: Some("RunMat:feedback:Internal"),
100        when: "Closed-loop transfer-function assembly failed.",
101        message: "feedback: internal error",
102    },
103];
104pub const FEEDBACK_DESCRIPTOR: BuiltinDescriptor = BuiltinDescriptor {
105    signatures: &FEEDBACK_SIGNATURES,
106    output_mode: BuiltinOutputMode::Fixed,
107    completion_policy: BuiltinCompletionPolicy::Public,
108    errors: &FEEDBACK_ERRORS,
109};
110
111#[runmat_macros::register_gpu_spec(builtin_path = "crate::builtins::control::feedback")]
112pub const GPU_SPEC: BuiltinGpuSpec = BuiltinGpuSpec {
113    name: "feedback",
114    op_kind: GpuOpKind::Custom("control-feedback-interconnection"),
115    supported_precisions: &[],
116    broadcast: BroadcastSemantics::None,
117    provider_hooks: &[],
118    constant_strategy: ConstantStrategy::InlineLiteral,
119    residency: ResidencyPolicy::GatherImmediately,
120    nan_mode: ReductionNaN::Include,
121    two_pass_threshold: None,
122    workgroup_size: None,
123    accepts_nan_mode: false,
124    notes: "SISO transfer-function interconnection runs on host-side metadata.",
125};
126
127#[runmat_macros::register_fusion_spec(builtin_path = "crate::builtins::control::feedback")]
128pub const FUSION_SPEC: BuiltinFusionSpec = BuiltinFusionSpec {
129    name: "feedback",
130    shape: ShapeRequirements::Any,
131    constant_strategy: ConstantStrategy::InlineLiteral,
132    elementwise: None,
133    reduction: None,
134    emits_nan: false,
135    notes: "feedback creates a transfer-function object and terminates numeric fusion chains.",
136};
137
138fn feedback_error(
139    message: impl Into<String>,
140    error: &'static BuiltinErrorDescriptor,
141) -> RuntimeError {
142    let mut builder = crate::build_runtime_error(message).with_builtin(BUILTIN_NAME);
143    if let Some(identifier) = error.identifier {
144        builder = builder.with_identifier(identifier);
145    }
146    builder.build()
147}
148
149#[runtime_builtin(
150    name = "feedback",
151    category = "control",
152    summary = "Form SISO feedback interconnections for transfer-function models.",
153    keywords = "feedback,control system,closed loop,transfer function,tf",
154    type_resolver(feedback_type),
155    descriptor(crate::builtins::control::feedback::FEEDBACK_DESCRIPTOR),
156    builtin_path = "crate::builtins::control::feedback"
157)]
158async fn feedback_builtin(sys1: Value, rest: Vec<Value>) -> BuiltinResult<Value> {
159    if rest.len() > 2 {
160        return Err(feedback_error(
161            "feedback: expected feedback(sys1), feedback(sys1, sys2), or feedback(sys1, sys2, sign)",
162            &FEEDBACK_ERRORS[0],
163        ));
164    }
165    let sys2 = rest.first().cloned().unwrap_or(Value::Num(1.0));
166    let sign = match rest.get(1) {
167        Some(value) => {
168            let gathered = crate::dispatcher::gather_if_needed_async(value).await?;
169            scalar_f64(&gathered, "sign", BUILTIN_NAME)?
170        }
171        None => -1.0,
172    };
173    if sign != -1.0 && sign != 1.0 {
174        return Err(feedback_error(
175            "feedback: sign must be -1 or +1",
176            &FEEDBACK_ERRORS[2],
177        ));
178    }
179
180    let (forward, feedback_path) = two_models_ordered(sys1, sys2, BUILTIN_NAME).await?;
181    forward
182        .feedback(&feedback_path, sign)?
183        .to_value(BUILTIN_NAME)
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use futures::executor::block_on;
190    use runmat_builtins::Tensor;
191
192    fn tf(num: Vec<f64>, den: Vec<f64>) -> Value {
193        block_on(crate::call_builtin_async(
194            "tf",
195            &[
196                Value::Tensor(Tensor::new(num.clone(), vec![1, num.len()]).unwrap()),
197                Value::Tensor(Tensor::new(den.clone(), vec![1, den.len()]).unwrap()),
198            ],
199        ))
200        .expect("tf")
201    }
202
203    fn coeff(value: &Value, field: &str) -> Vec<f64> {
204        let Value::Object(object) = value else {
205            panic!("expected tf object");
206        };
207        let Value::Tensor(tensor) = object.properties.get(field).expect(field) else {
208            panic!("expected tensor");
209        };
210        tensor.data.clone()
211    }
212
213    #[test]
214    fn unity_negative_feedback_forms_closed_loop() {
215        let g = tf(vec![2.0], vec![1.0, 3.0]);
216        let out = block_on(feedback_builtin(g, vec![Value::Num(1.0)])).expect("feedback");
217        assert_eq!(coeff(&out, "Numerator"), vec![2.0]);
218        assert_eq!(coeff(&out, "Denominator"), vec![1.0, 5.0]);
219    }
220
221    #[test]
222    fn positive_feedback_subtracts_loop_gain() {
223        let g = tf(vec![2.0], vec![1.0, 3.0]);
224        let out = block_on(feedback_builtin(g, vec![Value::Num(1.0), Value::Num(1.0)]))
225            .expect("feedback");
226        assert_eq!(coeff(&out, "Numerator"), vec![2.0]);
227        assert_eq!(coeff(&out, "Denominator"), vec![1.0, 1.0]);
228    }
229}
runmat_runtime/builtins/control/feedback.rs

runmat_runtime/builtins/control/
feedback.rs
