rename Dims()->SystemDims()

Author: soypat

filter.go

@@ -6,7 +6,8 @@ import (
 
 // Filter is a dynamical system filter.
 type Filter interface {
-	// Predict returns the expected change in internal state
+	// Predict returns a prediction of which will be
+	// next internal state
 	Predict(x, u mat.Vector) (Estimate, error)
 	// Update returns estimated system state based on external measurement ym.
 	Update(x, u, ym mat.Vector) (Estimate, error)
@@ -32,15 +33,15 @@ type Model interface {
 	Propagator
 	// Observer is system observer
 	Observer
-	// Dims returns the dimension of state vector, input vector,
+	// SystemDims returns the dimension of state vector, input vector,
 	// output (measurements, written as y) vector and disturbance vector (only dynamical systems).
-	// Below are dimension of matrices as returned by Dims() (row,column)
-	//  nx, nx = A.Dims()
-	//  nx, nu = B.Dims()
-	//  ny, nx = C.Dims()
-	//  ny, nu = D.Dims()
-	//  nx, nz = E.Dims()
-	Dims() (nx, nu, ny, nz int)
+	// Below are dimension of matrices as returned by SystemDims() (row,column)
+	//  nx, nx = A.SystemDims()
+	//  nx, nu = B.SystemDims()
+	//  ny, nx = C.SystemDims()
+	//  ny, nu = D.SystemDims()
+	//  nx, nz = E.SystemDims()
+	SystemDims() (nx, nu, ny, nz int)
 }
 
 // Smoother is a filter smoother
@@ -55,13 +56,13 @@ type DiscreteModel interface {
 	// Model is a model of a dynamical system
 	Model
 	// SystemMatrix returns state propagation matrix
-	SystemMatrix() (A mat.Matrix) // TODO rename to SystemMatrix
+	SystemMatrix() (A mat.Matrix)
 	// ControlMatrix returns state propagation control matrix
-	ControlMatrix() (B mat.Matrix) // TODO rename to ControlMatrix
+	ControlMatrix() (B mat.Matrix)
 	// OutputMatrix returns observation matrix
 	OutputMatrix() (C mat.Matrix)
 	// FeedForwardMatrix returns observation control matrix
-	FeedForwardMatrix() (D mat.Matrix) // TODO Rename to FeedMatrix/FeedForwardMatrix
+	FeedForwardMatrix() (D mat.Matrix)
 	// TODO DisturbanceMatrix
 }
 

kalman/ekf/ekf.go

@@ -50,7 +50,7 @@ type EKF struct {
 // - invalid state or output noise is given: noise covariance must either be nil or match the model dimensions
 func New(m filter.Model, init filter.InitCond, q, r filter.Noise) (*EKF, error) {
 	// size of the input and output vectors
-	nx, _, ny, _ := m.Dims()
+	nx, _, ny, _ := m.SystemDims()
 	if nx <= 0 || ny <= 0 {
 		return nil, fmt.Errorf("invalid model dimensions: [%d x %d]", nx, ny)
 	}
@@ -174,7 +174,7 @@ func (k *EKF) Predict(x, u mat.Vector) (filter.Estimate, error) {
 // Update corrects state x using the measurement z, given control intput u and returns corrected estimate.
 // It returns error if either invalid state was supplied or if it fails to calculate system output estimate.
 func (k *EKF) Update(x, u, z mat.Vector) (filter.Estimate, error) {
-	nx, _, ny, _ := k.m.Dims()
+	nx, _, ny, _ := k.m.SystemDims()
 
 	if z.Len() != ny {
 		return nil, fmt.Errorf("invalid measurement supplied: %v", z)

kalman/ekf/ekf_test.go

@@ -15,8 +15,8 @@ type invalidModel struct {
 	filter.Model
 }
 
-func (m *invalidModel) Dims() (nx, nu, ny, nz int) {
-	return -10, 0, 8, 0
+func (m *invalidModel) SystemDims() (nx, nu, ny, nz int) {
+	return -10, 0, 8, 0 // a system may have 0 inputs, this is not "invalid". Negative dimension is invalid
 }
 
 var (

kalman/ekf/iekf.go

@@ -49,9 +49,9 @@ func NewIter(m filter.Model, ic filter.InitCond, q, r filter.Noise, n int) (*IEK
 // Update corrects state x using the measurement z, given control intput u and returns corrected estimate of x.
 // It returns error if either invalid state was supplied or if it fails to calculate system output estimate.
 func (k *IEKF) Update(x, u, z mat.Vector) (filter.Estimate, error) {
-	_nx, _, _ny, _ := k.m.Dims()
+	nx, _, ny, _ := k.m.SystemDims()
 
-	if z.Len() != _ny {
+	if z.Len() != ny {
 		return nil, fmt.Errorf("invalid measurement supplied: %v", z)
 	}
 
@@ -61,8 +61,8 @@ func (k *IEKF) Update(x, u, z mat.Vector) (filter.Estimate, error) {
 		return nil, fmt.Errorf("failed to observe system output: %v", err)
 	}
 
-	pxy := mat.NewDense(_nx, _ny, nil)
-	pyy := mat.NewDense(_ny, _ny, nil)
+	pxy := mat.NewDense(nx, ny, nil)
+	pyy := mat.NewDense(ny, ny, nil)
 
 	// innovation vector
 	inn := &mat.VecDense{}
@@ -139,8 +139,8 @@ func (k *IEKF) Update(x, u, z mat.Vector) (filter.Estimate, error) {
 	k.inn.CopyVec(inn)
 	k.k.Copy(gain)
 	// update EKF covariance matrix
-	for i := 0; i < _nx; i++ {
-		for j := i; j < _nx; j++ {
+	for i := 0; i < nx; i++ {
+		for j := i; j < nx; j++ {
 			k.p.SetSym(i, j, pCorr.At(i, j))
 		}
 	}

kalman/kf/kf.go

@@ -39,47 +39,47 @@ type KF struct {
 //  - invalid state or output noise is given: noise covariance must either be nil or match the model dimensions
 func New(m filter.DiscreteModel, init filter.InitCond, z, wn filter.Noise) (*KF, error) {
 	// size of the input and output vectors
-	_nx, _, _ny, _ := m.Dims()
-	if _nx <= 0 || _ny <= 0 {
-		return nil, fmt.Errorf("invalid model dimensions: [%d x %d]", _nx, _ny)
+	nx, _, ny, _ := m.SystemDims()
+	if nx <= 0 || ny <= 0 {
+		return nil, fmt.Errorf("invalid model dimensions: [%d x %d]", nx, ny)
 	}
 
 	if z != nil {
-		if z.Cov().Symmetric() != _nx {
-			return nil, fmt.Errorf("invalid state noise dimension: %d != %d", z.Cov().Symmetric(), _ny)
+		if z.Cov().Symmetric() != nx {
+			return nil, fmt.Errorf("invalid state noise dimension: %d != %d", z.Cov().Symmetric(), ny)
 		}
 	} else {
 		z, _ = noise.NewNone()
 	}
 
 	if wn != nil {
-		if wn.Cov().Symmetric() != _ny {
+		if wn.Cov().Symmetric() != ny {
 			return nil, fmt.Errorf("invalid output noise dimension: %d", wn.Cov().Symmetric())
 		}
 	} else {
 		wn, _ = noise.NewNone()
 	}
 
 	rows, cols := m.SystemMatrix().Dims()
-	if rows != _nx || cols != _nx {
+	if rows != nx || cols != nx {
 		return nil, fmt.Errorf("invalid propagation matrix dimensions: [%d x %d]", rows, cols)
 	}
 
 	if m.ControlMatrix() != nil && !m.ControlMatrix().(*mat.Dense).IsEmpty() {
 		rows, cols := m.ControlMatrix().Dims()
-		if rows != _nx {
+		if rows != nx {
 			return nil, fmt.Errorf("invalid ctl propagation matrix dimensions: [%d x %d]", rows, cols)
 		}
 	}
 
 	rows, cols = m.OutputMatrix().Dims()
-	if rows != _ny || cols != _nx {
+	if rows != ny || cols != nx {
 		return nil, fmt.Errorf("invalid observation matrix dimensions: [%d x %d]", rows, cols)
 	}
 
 	if m.FeedForwardMatrix() != nil && !m.FeedForwardMatrix().(*mat.Dense).IsEmpty() {
 		rows, cols = m.FeedForwardMatrix().Dims()
-		if rows != _ny {
+		if rows != ny {
 			return nil, fmt.Errorf("invalid ctl observation matrix dimensions: [%d x %d]", rows, cols)
 		}
 	}
@@ -92,10 +92,10 @@ func New(m filter.DiscreteModel, init filter.InitCond, z, wn filter.Noise) (*KF,
 	pNext := mat.NewSymDense(init.Cov().Symmetric(), nil)
 
 	// innovation vector
-	inn := mat.NewVecDense(_ny, nil)
+	inn := mat.NewVecDense(ny, nil)
 
 	// kalman gain
-	k := mat.NewDense(_nx, _ny, nil)
+	k := mat.NewDense(nx, ny, nil)
 
 	return &KF{
 		m:     m,
@@ -140,9 +140,9 @@ func (k *KF) Predict(x, u mat.Vector) (filter.Estimate, error) {
 // Update corrects state x using the measurement z, given control intput u and returns corrected estimate.
 // It returns error if either invalid state was supplied or if it fails to calculate system output estimate.
 func (k *KF) Update(x, u, ym mat.Vector) (filter.Estimate, error) {
-	_nx, _, _ny, _ := k.m.Dims()
+	nx, _, ny, _ := k.m.SystemDims()
 
-	if ym.Len() != _ny {
+	if ym.Len() != ny {
 		return nil, fmt.Errorf("invalid measurement supplied: %v", ym)
 	}
 
@@ -152,8 +152,8 @@ func (k *KF) Update(x, u, ym mat.Vector) (filter.Estimate, error) {
 		return nil, fmt.Errorf("failed to observe system output: %v", err)
 	}
 
-	pxy := mat.NewDense(_nx, _ny, nil)
-	pyy := mat.NewDense(_ny, _ny, nil)
+	pxy := mat.NewDense(nx, ny, nil)
+	pyy := mat.NewDense(ny, ny, nil)
 
 	// P*H'
 	pxy.Mul(k.pNext, k.m.OutputMatrix().T())
@@ -217,8 +217,8 @@ func (k *KF) Update(x, u, ym mat.Vector) (filter.Estimate, error) {
 	k.inn.CopyVec(inn)
 	k.k.Copy(gain)
 	// update KF covariance matrix
-	for i := 0; i < _nx; i++ {
-		for j := i; j < _nx; j++ {
+	for i := 0; i < nx; i++ {
+		for j := i; j < nx; j++ {
 			k.p.SetSym(i, j, pCorr.At(i, j))
 		}
 	}

kalman/kf/kf_test.go

@@ -13,12 +13,13 @@ import (
 
 type invalidModel struct {
 	filter.DiscreteModel
-	r int
-	c int
+	nx int
+	nu int
+	ny int
 }
 
-func (m *invalidModel) Dims() (nx, nu, ny, nz int) {
-	return m.r, 0, m.c, 0
+func (m *invalidModel) SystemDims() (nx, nu, ny, nz int) {
+	return m.nx, m.nu, m.ny, 0
 }
 
 var (
@@ -50,7 +51,7 @@ func setup() {
 	D := mat.NewDense(1, 1, []float64{0.0})
 
 	okModel = &sim.BaseModel{A: A, B: B, C: C, D: D}
-	badModel = &invalidModel{DiscreteModel: okModel, r: 10, c: 10}
+	badModel = &invalidModel{DiscreteModel: okModel, nx: 10, ny: 10}
 }
 
 func TestMain(m *testing.M) {
@@ -70,7 +71,7 @@ func TestKFNew(t *testing.T) {
 	assert.NotNil(f)
 
 	// invalid model: negative dimensions
-	badModel.r, badModel.c = -10, 20
+	badModel.nx, badModel.ny = -10, 20
 	f, err = New(badModel, ic, q, r)
 	assert.Nil(f)
 	assert.Error(err)