export balance_statespace (#609)

- add test
- fix docstring

src/ControlSystems.jl

@@ -14,6 +14,7 @@ export  LTISystem,
         isproper,
         # Linear Algebra
         balance,
+        balance_statespace,
         care,
         dare,
         dlyap,

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

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