mark linear analysis interface as experimental

Author: baggepinnen

docs/src/API/linear_analysis.md

@@ -1,11 +1,14 @@
 # Linear Analysis
 
-Linear analysis refers to the process of linearizing a nonlinear model and analysing the resulting linear dynamical system. To facilitate linear analysis, ModelingToolkitStandardLibrary provides the concept of an [`AnalysisPoint`](@ref), which can be inserted inbetween two causal blocks (such as those from the Blocks sub module). Once a model containing analysis points is built, several operations are available:
+!!! danger "Experimental"
+    The interface described here is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
+Linear analysis refers to the process of linearizing a nonlinear model and analysing the resulting linear dynamical system. To facilitate linear analysis, ModelingToolkitStandardLibrary provides the concept of an [`AnalysisPoint`](@ref), which can be inserted in-between two causal blocks (such as those from the `Blocks` sub module). Once a model containing analysis points is built, several operations are available:
 
 - [`get_sensitivity`](@ref) get the [sensitivity function (wiki)](https://en.wikipedia.org/wiki/Sensitivity_(control_systems)), $S(s)$, as defined in the field of control theory.
-- [`get_comp_sensitivity`](@ref) get the complementary sensitivy function $T(s) : S(s)+T(s)=1$.
+- [`get_comp_sensitivity`](@ref) get the complementary sensitivity function $T(s) : S(s)+T(s)=1$.
 - [`get_looptransfer`](@ref) get the (open) loop-transfer function where the loop starts and ends in the analysis point.
-- [`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearied system. Parts of the model not appearing between the input and output will be removed.
+- [`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearized system. Parts of the model not appearing between the input and output will be removed.
 - [`open_loop`](@ref) return a new (nonlinear) system where the loop has been broken in the analysis point, i.e., the connection the analysis point usually implies has been removed.
 
 An analysis point can be created explicitly using the constructor [`AnalysisPoint`](@ref), or automatically when connecting two causal components using `connect`:
@@ -94,4 +97,4 @@ Modules = [ModelingToolkitStandardLibrary.Blocks]
 Pages   = ["Blocks/analysis_points.jl"]
 Order   = [:function, :type]
 Private = false
-```
+```

src/Blocks/analysis_points.jl

@@ -16,6 +16,9 @@ Create an AnalysisPoint for linear analysis. Analysis points can also be created
 connect(in, :ap_name, out)
 ```
 
+!!! danger "Experimental"
+    The analysis-point interface is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
 # Arguments:
 - `in`: A connector of type [`RealOutput`](@ref).
 - `out`: A connector of type [`RealInput`](@ref).
@@ -149,6 +152,9 @@ end
 
 Compute the sensitivity function in analysis point `ap`. The sensitivity function is obtained by introducing an infinitesimal perturbation `d` at the input of `ap`, linearizing the system and computing the transfer function between `d` and the output of `ap`.
 
+!!! danger "Experimental"
+    The analysis-point interface is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
 # Arguments:
 - `kwargs`: Are sent to `ModelingToolkit.linearize`
 
@@ -178,6 +184,9 @@ end
 
 Compute the complementary sensitivity function in analysis point `ap`. The complementary sensitivity function is obtained by introducing an infinitesimal perturbation `d` at the output of `ap`, linearizing the system and computing the transfer function between `d` and the input of `ap`.
 
+!!! danger "Experimental"
+    The analysis-point interface is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
 # Arguments:
 - `kwargs`: Are sent to `ModelingToolkit.linearize`
 
@@ -208,6 +217,9 @@ end
 
 Compute the (linearized) loop-transfer function in analysis point `ap`, from `ap.out` to `ap.in`.
 
+!!! danger "Experimental"
+    The analysis-point interface is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
 # Arguments:
 - `kwargs`: Are sent to `ModelingToolkit.linearize`
 
@@ -236,6 +248,9 @@ Open the loop at analysis point `ap` by breaking the connection through `ap`.
 
 `open_sys` will have `u ~ ap.out` as input and `y ~ ap.in` as output.
 
+!!! danger "Experimental"
+    The analysis-point interface is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
 # Arguments:
 - `kwargs`: Are sent to `ModelingToolkit.linearize`