From 094983a12649ada131af4af012d3a206622181a9 Mon Sep 17 00:00:00 2001
From: Fredrik Bagge Carlson <baggepinnen@gmail.com>
Date: Tue, 25 Jan 2022 07:34:45 +0100
Subject: [PATCH] export balance_statespace (#609)

- add test
- fix docstring
---
 src/ControlSystems.jl     | 1 +
 src/types/conversion.jl   | 9 +++++----
 test/test_matrix_comps.jl | 1 +
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/ControlSystems.jl b/src/ControlSystems.jl
index 3b09588b1..ec13bc56c 100644
--- a/src/ControlSystems.jl
+++ b/src/ControlSystems.jl
@@ -14,6 +14,7 @@ export  LTISystem,
         isproper,
         # Linear Algebra
         balance,
+        balance_statespace,
         care,
         dare,
         dlyap,
diff --git a/src/types/conversion.jl b/src/types/conversion.jl
index 701fdb1ba..9994c5f4d 100644
--- a/src/types/conversion.jl
+++ b/src/types/conversion.jl
@@ -156,15 +156,16 @@ function siso_tf_to_ss(T::Type, f::SisoRational)
 end
 
 """
-`A, B, C, T = balance_statespace{S}(A::Matrix{S}, B::Matrix{S}, C::Matrix{S}, perm::Bool=false)`
-
-`sys, T = balance_statespace(sys::StateSpace, perm::Bool=false)`
+    A, B, C, T = balance_statespace{S}(A::Matrix{S}, B::Matrix{S}, C::Matrix{S}, perm::Bool=false)
+    sys, T = balance_statespace(sys::StateSpace, perm::Bool=false)
 
 Computes a balancing transformation `T` that attempts to scale the system so
 that the row and column norms of [T*A/T T*B; C/T 0] are approximately equal.
 If `perm=true`, the states in `A` are allowed to be reordered.
 
-This is not the same as finding a balanced realization with equal and diagonal observability and reachability gramians, see `balreal`
+The inverse of `sysb, T = balance_statespace(sys)` is given by `similarity_transform(sysb, T)`
+
+This is not the same as finding a balanced realization with equal and diagonal observability and reachability gramians, see [`balreal`](@ref)
 """
 function balance_statespace(A::AbstractMatrix, B::AbstractMatrix, C::AbstractMatrix, perm::Bool=false)
     try
diff --git a/test/test_matrix_comps.jl b/test/test_matrix_comps.jl
index b22ed9445..428561ab9 100644
--- a/test/test_matrix_comps.jl
+++ b/test/test_matrix_comps.jl
@@ -11,6 +11,7 @@ sysr, G = balreal(sys)
 @test sort(poles(sysr)) ≈ sort(poles(sys))
 
 sysb,T = ControlSystems.balance_statespace(sys)
+@test similarity_transform(sysb, T) ≈ sys
 Ab,Bb,Cb,T = ControlSystems.balance_statespace(A,B,C)
 
 @test Ab*T ≈ T*A