diff --git a/symbolic/basic_environment.go b/symbolic/basic_environment.go index b7acf94..f89a416 100644 --- a/symbolic/basic_environment.go +++ b/symbolic/basic_environment.go @@ -1,14 +1,19 @@ package symbolic +// BasicEnvironment is a simple implementation of the Environment interface +// that tracks variables in a slice. type BasicEnvironment struct { name string Variables []Variable } +// GetName returns the name of the environment. func (be *BasicEnvironment) GetName() string { return be.name } +// TrackVariable adds the variable to the environment if it is not already +// tracked. Returns true if the variable was added, false if it already exists. func (be *BasicEnvironment) TrackVariable(v Variable) bool { // Check if the variable is already in the environment for _, existingVar := range be.Variables { @@ -23,14 +28,12 @@ func (be *BasicEnvironment) TrackVariable(v Variable) bool { return true // Variable was added successfully } +// AllTrackedVariables returns a slice of all variables tracked by the environment. func (be *BasicEnvironment) AllTrackedVariables() []Variable { return be.Variables } -/* -Public Functions -*/ - +// MakeBasicEnvironment creates a new BasicEnvironment with the given name. func MakeBasicEnvironment(nameIn string) BasicEnvironment { return BasicEnvironment{ name: nameIn, @@ -38,8 +41,5 @@ func MakeBasicEnvironment(nameIn string) BasicEnvironment { } } -/* -DefaultEnvironment -A variable that exists in the background and used to store information about the variables currently created. -*/ +// DefaultEnvironment A variable that exists in the background and used to store information about the variables currently created. var DefaultEnvironment = MakeBasicEnvironment("DefaultEnvironment") diff --git a/symbolic/constant.go b/symbolic/constant.go index ee2485c..149b2e0 100644 --- a/symbolic/constant.go +++ b/symbolic/constant.go @@ -20,25 +20,15 @@ const ( // K is a constant expression type for an MIP. K for short ¯\_(ツ)_/¯ type K float64 -/* -Check -Description: - - Checks to make sure that the constant is initialized properly. - Constants are always initialized properly, so this should always return - no error. -*/ +// Check Checks to make sure that the constant is initialized properly. +// Constants are always initialized properly, so this should always return +// no error. func (c K) Check() error { return nil } -/* -Variables -Description: - - Shares all variables included in the expression that is K. - It is a constant, so there are none. -*/ +// Variables Shares all variables included in the expression that is K. +// It is a constant, so there are none. func (c K) Variables() []Variable { return []Variable{} } @@ -49,13 +39,8 @@ func (c K) Constant() float64 { return float64(c) } -/* -LinearCoeff -Description - - Returns the coefficient of the linear term in the expression. For a constant, - this is always a matrix of zeros. -*/ +// LinearCoeff Returns the coefficient of the linear term in the expression. For a constant, +// this is always a matrix of zeros. func (c K) LinearCoeff(wrt ...[]Variable) mat.VecDense { // Constants @@ -78,12 +63,7 @@ func (c K) LinearCoeff(wrt ...[]Variable) mat.VecDense { return ZerosVector(len(wrtVars)) } -/* -Plus -Description: - - adds the current expression to another and returns the resulting expression -*/ +// Plus adds the current expression to another and returns the resulting expression func (c K) Plus(rightIn interface{}) Expression { // Input Processing if IsExpression(rightIn) { @@ -141,12 +121,7 @@ func (c K) Plus(rightIn interface{}) Expression { ) } -/* -Minus -Description: - - This function subtracts the current expression from another and returns the resulting expression. -*/ +// Minus This function subtracts the current expression from another and returns the resulting expression. func (c K) Minus(rightIn interface{}) Expression { // Input Processing if IsExpression(rightIn) { @@ -198,12 +173,7 @@ func (c K) Eq(rightIn interface{}) Constraint { return c.Comparison(rightIn, SenseEqual) } -/* -Comparison -Description: - - This method compares the receiver with expression rhs in the sense provided by sense. -*/ +// Comparison This method compares the receiver with expression rhs in the sense provided by sense. func (c K) Comparison(rhsIn interface{}, sense ConstrSense) Constraint { // InputProcessing if IsExpression(rhsIn) { @@ -271,12 +241,7 @@ func (c K) Comparison(rhsIn interface{}, sense ConstrSense) Constraint { } -/* -Multiply -Description: - - This method multiplies the input constant by another expression. -*/ +// Multiply This method multiplies the input constant by another expression. func (c K) Multiply(term1 interface{}) Expression { // Constants @@ -321,20 +286,17 @@ func (c K) Multiply(term1 interface{}) Expression { ) } +// Dims returns the dimensions of the constant K as a scalar [1, 1]. func (c K) Dims() []int { return []int{1, 1} // Signifies scalar } +// Transpose returns the constant itself, as the transpose of a scalar is itself. func (c K) Transpose() Expression { return c } -/* -ToMonomial -Description: - - Converts the constant into a monomial. -*/ +// ToMonomial Converts the constant into a monomial. func (c K) ToMonomial() Monomial { return Monomial{ Coefficient: float64(c), @@ -343,89 +305,48 @@ func (c K) ToMonomial() Monomial { } } -/* -ToPolynomial -Description: - - Converts the constant into a polynomial. -*/ +// ToPolynomial Converts the constant into a polynomial. func (c K) ToPolynomial() Polynomial { return Polynomial{ Monomials: []Monomial{c.ToMonomial()}, } } -/* -DerivativeWrt -Description: - - Computes the derivative of a constant, which should be 0 for any constant. -*/ +// DerivativeWrt Computes the derivative of a constant, which should be 0 for any constant. func (c K) DerivativeWrt(vIn Variable) Expression { return Zero } -/* -Degree -Description: - - The degree of a constant is always 0. -*/ +// Degree The degree of a constant is always 0. func (c K) Degree() int { return 0 } -/* -String -Description: - - Returns a string representation of the constant. -*/ +// String Returns a string representation of the constant. func (c K) String() string { return fmt.Sprintf("%v", float64(c)) } -/* -Substitute -Description: - - Substitutes the variable vIn with the expression eIn. -*/ +// Substitute Substitutes the variable vIn with the expression eIn. func (c K) Substitute(vIn Variable, eIn ScalarExpression) Expression { return c } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo Substitutes the variables in the map with the corresponding expressions. func (c K) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { return c } -/* -Power -Description: - - Computes the power of the constant. -*/ +// Power computes the result of the constant taken to the given exponent. func (c K) Power(exponent int) Expression { return ScalarPowerTemplate(c, exponent) } -/* -At -Description: - - Returns the value at the given row and column index. - -Note: - - For a constant, this is always the constant itself. - The value of ii and jj should always be 0. -*/ +// At Returns the value at the given row and column index. +// Note: +// +// For a constant, this is always the constant itself. +// The value of ii and jj should always be 0. func (c K) At(ii, jj int) ScalarExpression { // Input Processing @@ -438,12 +359,7 @@ func (c K) At(ii, jj int) ScalarExpression { return c } -/* -AsSimplifiedExpression -Description: - - Returns the simplest form of the expression. -*/ +// AsSimplifiedExpression Returns the simplest form of the expression. func (c K) AsSimplifiedExpression() Expression { return c } diff --git a/symbolic/constant_matrix.go b/symbolic/constant_matrix.go index 75e5ba1..3ac79f9 100644 --- a/symbolic/constant_matrix.go +++ b/symbolic/constant_matrix.go @@ -7,32 +7,17 @@ import ( "gonum.org/v1/gonum/mat" ) -/* -constant_matrix.go -Description: - Defines all methods related to the constant matrix type. -*/ - +// KMatrix defines all methods related to the constant matrix type. type KMatrix [][]K -/* -Check -Description: - - Checks to make sure that the constant is initialized properly. - ConstantMatrix objects are always initialized properly, so this should always return - no error. -*/ +// Check Checks to make sure that the constant is initialized properly. +// ConstantMatrix objects are always initialized properly, so this should always return +// no error. func (km KMatrix) Check() error { return nil } -/* -ToDense -Description: - - Converts the constant matrix to a dense matrix. -*/ +// ToDense Converts the constant matrix to a mat.Dense matrix from the gonum library. func (km KMatrix) ToDense() mat.Dense { // Input Checking err := km.Check() @@ -55,22 +40,12 @@ func (km KMatrix) ToDense() mat.Dense { return *kmAsDense } -/* -Variables -Description: - - There are no variables in the constant matrix. -*/ +// Variables returns the number of variables contained in the constant matrix. (There are no variables in the constant matrix.) func (km KMatrix) Variables() []Variable { return []Variable{} } -/* -Dims -Description: - - The dimensions of the given matrix. -*/ +// Dims The dimensions of the given matrix. func (km KMatrix) Dims() []int { // Input Checking err := km.Check() @@ -80,12 +55,7 @@ func (km KMatrix) Dims() []int { return []int{len(km), len(km[0])} } -/* -Plus -Description: - - Addition of the constant matrix with another expression. -*/ +// Plus returns the sum of the constant matrix with another expression. func (km KMatrix) Plus(e interface{}) Expression { // Input Processing err := km.Check() @@ -166,12 +136,7 @@ func (km KMatrix) Plus(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - Subtraction of the constant matrix with another expression. -*/ +// Minus Subtraction of the constant matrix with another expression. func (km KMatrix) Minus(e interface{}) Expression { // Input Processing err := km.Check() @@ -219,12 +184,7 @@ func (km KMatrix) Minus(e interface{}) Expression { ) } -/* -Multiply -Description: - - Multiplication of the constant matrix with another expression. -*/ +// Multiply Multiplication of the constant matrix with another expression. func (km KMatrix) Multiply(e interface{}) Expression { // Input Processing err := km.Check() @@ -353,13 +313,8 @@ func (km KMatrix) Multiply(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - Transposes the constant matrix and returns a new - matrix. -*/ +// Transpose Transposes the constant matrix and returns a new +// matrix. func (km KMatrix) Transpose() Expression { // Constants @@ -382,49 +337,29 @@ func (km KMatrix) Transpose() Expression { } -/* -LessEq -Description: - - Returns a constraint between the KMatrix and the - expression on the right hand side. -*/ +// LessEq Returns a "Less Than or Equal To" constraint between the KMatrix and the +// expression on the right hand side. func (km KMatrix) LessEq(rightIn interface{}) Constraint { return km.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Returns a greater equal constraint between the KMatrix and the - expression on the right hand side. -*/ +// GreaterEq Returns a "greater than or equal to" constraint between the KMatrix and the +// expression rightIn, with rightIn being on the right hand side. func (km KMatrix) GreaterEq(rightIn interface{}) Constraint { return km.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - Returns an equal constraint between the KMatrix and the - expression on the right hand side. -*/ +// Eq Returns an equal constraint between the KMatrix and the +// expression on the right hand side. func (km KMatrix) Eq(rightIn interface{}) Constraint { return km.Comparison(rightIn, SenseEqual) } -/* -Comparison -Description: - - Returns a constraint between the KMatrix and the - expression on the right hand side. -*/ +// Comparison Returns a constraint between the KMatrix and the +// expression on the right hand side. func (km KMatrix) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing //err := km.Check() @@ -483,35 +418,20 @@ func (km KMatrix) Comparison(rightIn interface{}, sense ConstrSense) Constraint } -/* -At -Description: - - Retrieves element at the specified indices. -*/ +// At Retrieves element at the specified indices. func (km KMatrix) At(i, j int) ScalarExpression { kmAsD := km.ToDense() return K(kmAsD.At(i, j)) } -/* -Constant -Description: - - Retrieves the constant component. -*/ +// Constant Retrieves the constant component. func (km KMatrix) Constant() mat.Dense { return km.ToDense() } // Other Functions -/* -ZerosMatrix -Description: - - Returns a dense matrix of all zeros. -*/ +// ZerosMatrix Returns a dense matrix of all zeros. func ZerosMatrix(nR, nC int) mat.Dense { // Create empty slice elts := make([]float64, nR*nC) @@ -524,12 +444,7 @@ func ZerosMatrix(nR, nC int) mat.Dense { return *mat.NewDense(nR, nC, elts) } -/* -OnesMatrix -Description: - - Returns a dense matrix of all ones. -*/ +// OnesMatrix Returns a mat.Dense matrix (from gonum) of all ones. func OnesMatrix(nR, nC int) mat.Dense { // Create empty slice elts := make([]float64, nR*nC) @@ -542,13 +457,8 @@ func OnesMatrix(nR, nC int) mat.Dense { return *mat.NewDense(nR, nC, elts) } -/* -Identity -Description: - - Returns a symmetric matrix that is the identity matrix. - Note: this function assumes lengthIn is a positive number. -*/ +// Identity Returns the identity matrix of a given size (note that this matrix is symmetric). +// Note: this function assumes lengthIn is a positive number. func Identity(dim int) mat.Dense { // Create the empty matrix. zeroBase := ZerosMatrix(dim, dim) @@ -561,23 +471,13 @@ func Identity(dim int) mat.Dense { return zeroBase } -/* -DerivativeWrt -Description: - - Computes the derivative of the constant matrix with respect to the variable - v. For a constant matrix, this should create a matrix of all zeros (ZerosMatrix). -*/ +// DerivativeWrt Computes the derivative of the constant matrix with respect to the variable +// v. For a constant matrix, this should create a matrix of all zeros (ZerosMatrix). func (km KMatrix) DerivativeWrt(vIn Variable) Expression { return DenseToKMatrix(ZerosMatrix(km.Dims()[0], km.Dims()[1])) } -/* -String -Description: - - Returns a string representation of the constant matrix. -*/ +// String Returns a string representation of the constant matrix. func (km KMatrix) String() string { // Constants nR, nC := km.Dims()[0], km.Dims()[1] @@ -606,12 +506,7 @@ func (km KMatrix) String() string { return out } -/* -DenseToKMatrix -Description: - - Converts a dense matrix to a KMatrix. -*/ +// DenseToKMatrix Converts a dense matrix to a KMatrix. func DenseToKMatrix(denseIn mat.Dense) KMatrix { // Constants nR, nC := denseIn.Dims() @@ -631,12 +526,7 @@ func DenseToKMatrix(denseIn mat.Dense) KMatrix { return km } -/* -ToMonomialMatrix -Description: - - Converts the constant matrix to a monomial matrix. -*/ +// ToMonomialMatrix Converts the constant matrix to a monomial matrix. func (km KMatrix) ToMonomialMatrix() MonomialMatrix { // Constants nR, nC := km.Dims()[0], km.Dims()[1] @@ -654,12 +544,7 @@ func (km KMatrix) ToMonomialMatrix() MonomialMatrix { return mm } -/* -ToPolynomialMatrix -Description: - - Converts the constant matrix to a polynomial matrix. -*/ +// ToPolynomialMatrix Converts the constant matrix to a polynomial matrix. func (km KMatrix) ToPolynomialMatrix() PolynomialMatrix { // Constants nR, nC := km.Dims()[0], km.Dims()[1] @@ -677,53 +562,30 @@ func (km KMatrix) ToPolynomialMatrix() PolynomialMatrix { return pm } -/* -Degree -Description: - - The degree of a constant matrix is always 0. -*/ +// Degree returns the degree of the constant matrix (which is always 0). func (km KMatrix) Degree() int { return 0 } -/* -Substitute -Description: - - Substitutes all occurrences of variable vIn with the expression eIn. -*/ +// Substitute Substitutes all occurrences of variable vIn with the expression eIn. Because a constant matrix contains no variables, this function always returns the original matrix. func (km KMatrix) Substitute(vIn Variable, eIn ScalarExpression) Expression { return km } -/* -SubstituteAccordingTo -Description: - - Substitutes all occurrences of the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo Substitutes all occurrences of the variables in the map with the corresponding expressions. +// Similar to the above, there are no variables in a constant matrix and so this will always return the constant matrix. func (km KMatrix) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { return km } -/* -Power -Description: - - Raises the constant matrix to the power of the input integer. -*/ +// Power Raises the constant matrix to the power of the input integer. +// For now, this assumes that the power is positive. func (km KMatrix) Power(exponent int) Expression { return MatrixPowerTemplate(km, exponent) } -/* -AsSimplifiedExpression -Description: - - Simplifies the constant matrix. Since the constant matrix is always in simplest form, - this function simply returns the original constant matrix. -*/ +// AsSimplifiedExpression Simplifies the constant matrix. Since the constant matrix is always in simplest form, +// this function simply returns the original constant matrix. func (km KMatrix) AsSimplifiedExpression() Expression { return km } diff --git a/symbolic/constant_vector.go b/symbolic/constant_vector.go index bcbb093..60f4621 100644 --- a/symbolic/constant_vector.go +++ b/symbolic/constant_vector.go @@ -13,44 +13,24 @@ Description: Creates a vector extension of the constant type K from the original goop. */ -/* -KVector - - A type which is built on top of the KVector() - a constant expression type for an MIP. K for short ¯\_(ツ)_/¯ -*/ +// KVector A slice of constant (K) values, to be used as a VectorExpression. (and also an Expression) type KVector []K // Inherit all methods from mat.VecDense -/* -Len - - Computes the length of the KVector given. -*/ +// Len Computes the length of the KVector given. func (kv KVector) Len() int { return len(kv) } -/* -Check -Description: - - This method is used to make sure that the variable is well-defined. - For a constant vector, the vecdense should always be well-defined. -*/ +// Check This method is used to make sure that the variable is well-defined. +// For a constant vector, the slice should always be well-defined. This always returns no errors. func (kv KVector) Check() error { return nil } -/* -At -Description: - - This function returns the value at the ii, jj index. - -Note: - - For a constant vector, the jj index should always be 0. -*/ +// At This function returns the value at the ii, jj index. +// Note: +// +// For a constant vector, the jj index should always be 0. func (kv KVector) At(ii, jj int) ScalarExpression { // Input Processing @@ -65,12 +45,7 @@ func (kv KVector) At(ii, jj int) ScalarExpression { } -/* -AtVec -Description: - - This function returns the value at the k index. -*/ +// AtVec This function returns the value at the k index. func (kv KVector) AtVec(idx int) ScalarExpression { // Input Processing @@ -85,41 +60,23 @@ func (kv KVector) AtVec(idx int) ScalarExpression { return K(kvAsVector.AtVec(idx)) } -/* -Variables -Description: - - This function returns the empty slice because no variables are in a constant vector. -*/ +// Variables This function returns the empty slice because no variables are in a constant vector. func (kv KVector) Variables() []Variable { return []Variable{} } -/* -LinearCoeff -Description: - - This function returns a slice of the coefficients in the expression. For constants, this is always nil. -*/ +// LinearCoeff computes the linear coefficient vector that, when multiplied by kv.Variables(), can produce the given KVector kv. +// The constant vector contains no variables, so this vector is always an empty vector. I.e., this is always nil. func (kv KVector) LinearCoeff(wrt ...[]Variable) mat.Dense { return PolynomialLikeVector_SharedLinearCoeffCalc(kv, wrt...) } -/* -Constant - - Returns the constant additive value in the expression. For constants, this is just the constants value -*/ +// Constant Returns the constant additive value in the expression. For constants, this is just the constants value func (kv KVector) Constant() mat.VecDense { return kv.ToVecDense() } -/* -Plus -Description: - - Adds the current expression to another and returns the resulting expression -*/ +// Plus Adds the current expression to another and returns the resulting expression func (kv KVector) Plus(rightIn interface{}) Expression { // Input Processing err := kv.Check() @@ -182,12 +139,7 @@ func (kv KVector) Plus(rightIn interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - Subtracts the current expression from another and returns the resulting expression -*/ +// Minus subtracts an input expression from the current constant vector and returns the resulting expression func (kv KVector) Minus(e interface{}) Expression { // Input Processing err := kv.Check() @@ -240,36 +192,23 @@ func (kv KVector) Minus(e interface{}) Expression { ) } -/* -LessEq -Description: - - Returns a less than or equal to (<=) constraint between the current expression and another -*/ +// LessEq Returns a less than or equal to (<=) constraint between the current expression and another func (kv KVector) LessEq(rightIn interface{}) Constraint { return kv.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - This method returns a greater than or equal to (>=) constraint between the current expression and another -*/ +// GreaterEq returns a greater than or equal to (>=) constraint between the current expression and another func (kv KVector) GreaterEq(rightIn interface{}) Constraint { return kv.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - This method returns an equality (==) constraint between the current expression and another -*/ +// Eq returns an equality (==) constraint between the current expression and another func (kv KVector) Eq(rightIn interface{}) Constraint { return kv.Comparison(rightIn, SenseEqual) } +// Comparison creates a constraint comparing the KVector with the given +// expression in the sense provided by sense. func (kv KVector) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Checking err := kv.Check() @@ -332,12 +271,7 @@ func (kv KVector) Comparison(rightIn interface{}, sense ConstrSense) Constraint } } -/* -Multiply -Description: - - This method is used to compute the multiplication of the input vector constant with another term. -*/ +// Multiply returns the product of the input vector constant with another term. func (kv KVector) Multiply(rightIn interface{}) Expression { // Input Processing err := kv.Check() @@ -431,12 +365,7 @@ func (kv KVector) Multiply(rightIn interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - This method creates the transpose of the current vector and returns it. -*/ +// Transpose This method creates the transpose of the current vector and returns it. func (kv KVector) Transpose() Expression { // Constants kvAsVD := kv.ToVecDense() @@ -451,25 +380,15 @@ func (kv KVector) Transpose() Expression { return DenseToKMatrix(kvT) } -/* -Dims -Description: - - Returns the dimension of the constant vector. -*/ +// Dims Returns the dimension of the constant vector. func (kv KVector) Dims() []int { return []int{kv.Len(), 1} } // Other Functions -/* -OnesVector -Description: - - Returns a vector of ones with length lengthIn. - Note: this function assumes lengthIn is a positive number. -*/ +// OnesVector Returns a vector of ones with length lengthIn. +// Note: this function assumes lengthIn is a positive number. func OnesVector(lengthIn int) mat.VecDense { // Create the empty slice. elts := make([]float64, lengthIn) @@ -480,13 +399,8 @@ func OnesVector(lengthIn int) mat.VecDense { return *mat.NewVecDense(lengthIn, elts) } -/* -ZerosVector -Description: - - Returns a vector of zeros with length lengthIn. - Note: this function assumes lengthIn is a positive number. -*/ +// ZerosVector Returns a vector of zeros with length lengthIn. +// Note: this function assumes lengthIn is a positive number. func ZerosVector(lengthIn int) mat.VecDense { // Create the empty slice. elts := make([]float64, lengthIn) @@ -497,23 +411,13 @@ func ZerosVector(lengthIn int) mat.VecDense { return *mat.NewVecDense(lengthIn, elts) } -/* -DerivativeWrt -Description: - - Computes the derivative of the symbolic expression with respect to the - variable vIn which should be a vector of all zeros. -*/ +// DerivativeWrt Computes the derivative of the symbolic expression with respect to the +// variable vIn which should be a vector of all zeros. func (kv KVector) DerivativeWrt(vIn Variable) Expression { return VecDenseToKVector(ZerosVector(kv.Len())) } -/* -String -Description: - - Returns a string representation of the constant vector. -*/ +// String Returns a string representation of the constant vector. func (kv KVector) String() string { // Constants lenKV := kv.Len() @@ -531,12 +435,7 @@ func (kv KVector) String() string { return stringKV } -/* -ToVecDense -Description: - - This method converts the KVector to a mat.VecDense. -*/ +// ToVecDense This method converts the KVector to a mat.VecDense. func (kv KVector) ToVecDense() mat.VecDense { dataIn := make([]float64, kv.Len()) for ii, tempK := range kv { @@ -545,12 +444,7 @@ func (kv KVector) ToVecDense() mat.VecDense { return *mat.NewVecDense(len(kv), dataIn) } -/* -VecDenseToKVector -Description: - - This method converts the mat.VecDense to a KVector. -*/ +// VecDenseToKVector This method converts the mat.VecDense to a KVector. func VecDenseToKVector(v mat.VecDense) KVector { out := make([]K, v.Len()) for ii := 0; ii < v.Len(); ii++ { @@ -559,12 +453,7 @@ func VecDenseToKVector(v mat.VecDense) KVector { return out } -/* -ToMonomialVector -Description: - - This function converts the input expression to a monomial vector. -*/ +// ToMonomialVector This function converts the input expression to a monomial vector. func (kv KVector) ToMonomialVector() MonomialVector { // Input Processing err := kv.Check() @@ -582,12 +471,7 @@ func (kv KVector) ToMonomialVector() MonomialVector { return mvOut } -/* -ToPolynomialVector -Description: - - This function converts the input expression to a polynomial vector. -*/ +// ToPolynomialVector This function converts the input expression to a polynomial vector. func (kv KVector) ToPolynomialVector() PolynomialVector { return kv.ToMonomialVector().ToPolynomialVector() } @@ -597,62 +481,34 @@ ToKMatrix Description: */ -/* -Degree -Description: - - The degree of a constant matrix is always 0. -*/ +// Degree returns the polynomial degree of the constant vector. The degree of a constant vector is always 0. func (kv KVector) Degree() int { return 0 } -/* -Substitute -Description: - - Substitutes all occurrences of variable vIn with the expression eIn. -*/ +// Substitute Substitutes all occurrences of variable vIn with the expression eIn. +// Because a KVector contains no variables, this will always return a copy of the original vector. func (kv KVector) Substitute(vIn Variable, eIn ScalarExpression) Expression { return kv } -/* -SubstituteAccordingTo -Description: - - Substitutes all occurrences of the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo Substitutes all occurrences of the variables in the map with the corresponding expressions. +// As mentioned above, the constant vector contains no variables, so this substitution should always return the original constant vector. func (kv KVector) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { return kv } -/* -Power -Description: - - Raises the scalar expression to the power of the input integer. -*/ +// Power Raises the scalar expression to the power of the input integer. func (kv KVector) Power(exponent int) Expression { return VectorPowerTemplate(kv, exponent) } -/* -AsSimplifiedExpression -Description: - - Returns the simplest form of the expression. -*/ +// AsSimplifiedExpression Returns the simplest form of the expression. func (kv KVector) AsSimplifiedExpression() Expression { return kv } -/* -ToScalarExpressions -Description: - - Converts the KVector into a slice of ScalarExpression type objects. -*/ +// ToScalarExpressions Converts the KVector into a slice of ScalarExpression type objects. func (kv KVector) ToScalarExpressions() []ScalarExpression { var out []ScalarExpression for _, k := range kv { diff --git a/symbolic/constr_sense.go b/symbolic/constr_sense.go index 75d4bc0..e47ce75 100644 --- a/symbolic/constr_sense.go +++ b/symbolic/constr_sense.go @@ -14,6 +14,7 @@ const ( SenseGreaterThanEqual ConstrSense = '>' ) +// String returns a string representation of the constraint sense (e.g., "=", "<=", ">="). func (cs ConstrSense) String() string { switch cs { case SenseEqual: @@ -27,12 +28,7 @@ func (cs ConstrSense) String() string { } } -/* -Check -Description: - - This method checks if the receiver is one of the allowed types of sense. -*/ +// Check This method checks if the receiver is one of the allowed types of sense. func (cs ConstrSense) Check() error { switch cs { case SenseEqual: diff --git a/symbolic/constraint.go b/symbolic/constraint.go index e8a7e7f..ee39865 100644 --- a/symbolic/constraint.go +++ b/symbolic/constraint.go @@ -2,13 +2,8 @@ package symbolic import "fmt" -/* -constraint.go -Description: - Defines an interface that we are meant to use with the ScalarContraint and VectorConstraint - objects. -*/ - +// Constraint is a mathematical constraint (either <=, =, >=) between to expressions from SymbolicMath.go. +// This interface is later implemented by specific types like: ScalarConstraint, VectorConstraint, MatrixConstraint. type Constraint interface { Left() Expression Right() Expression @@ -35,6 +30,7 @@ type Constraint interface { // IsNonnegativityConstraint() bool } +// IsConstraint returns true if the given interface is a recognized Constraint type. func IsConstraint(c interface{}) bool { switch c.(type) { case ScalarConstraint: @@ -55,12 +51,7 @@ func IsConstraint(c interface{}) bool { return false } -/* -Variables -Description: - - Returns a slice of all the variables in the constraint. -*/ +// VariablesInThisConstraint returns a slice of all the variables in the constraint. func VariablesInThisConstraint(c Constraint) []Variable { // Setup varsMap := make(map[Variable]bool) @@ -90,13 +81,8 @@ func VariablesInThisConstraint(c Constraint) []Variable { return vars } -/* -CompileConstraintsIntoScalarConstraints -Description: - - This method analyzes all constraints in an OptimizationProblem and converts them all - into scalar constraints. -*/ +// CompileConstraintsIntoScalarConstraints This method analyzes all constraints in an OptimizationProblem and converts them all +// into scalar constraints. func CompileConstraintsIntoScalarConstraints(constraints []Constraint) []ScalarConstraint { // Setup var out []ScalarConstraint diff --git a/symbolic/environment.go b/symbolic/environment.go index eecc3a4..40cd29a 100644 --- a/symbolic/environment.go +++ b/symbolic/environment.go @@ -1,11 +1,6 @@ package symbolic -/* -environment.go -Description: - Defines the environment where the symbolic variables are stored. -*/ - +// Environment defines the environment where the symbolic variables are stored. type Environment interface { GetName() string TrackVariable(v Variable) bool diff --git a/symbolic/expression.go b/symbolic/expression.go index ec298cb..247fe9d 100644 --- a/symbolic/expression.go +++ b/symbolic/expression.go @@ -6,12 +6,9 @@ import ( "github.com/MatProGo-dev/SymbolicMath.go/smErrors" ) -/* -Expression -Description: - - This interface should be implemented by and ScalarExpression and VectorExpression -*/ +// Expression is a mathematical object that we can perform operations on with SymbolicMath.go. +// This interface should be implemented by any scalar, vector, etc. in the package. +// Similarly, useful interfaces like ScalarExpression should implement this interface. type Expression interface { // NumVars returns the number of variables in the expression Variables() []Variable @@ -75,22 +72,12 @@ type Expression interface { AsSimplifiedExpression() Expression } -/* -NumVariables -Description: - - The number of distinct variables. -*/ +// NumVariables returns the number of unique symbolic.Variable objects contained in this Expression. func NumVariables(e Expression) int { return len(e.Variables()) } -/* -VariableIDs -Description: - - Returns a list of ids associated with each variable. -*/ +// VariableIDs returns a list of the unique ids associated with each variable contained in this expression. func VariableIDs(e Expression) []uint64 { vSlice := e.Variables() @@ -102,16 +89,13 @@ func VariableIDs(e Expression) []uint64 { return idSlice } -/* -IsExpression -Description: - - Tests whether or not the input variable is one of the expression types. -*/ +// IsExpression Tests whether or not the input variable is one of the expression types. func IsExpression(e interface{}) bool { return IsScalarExpression(e) || IsVectorExpression(e) || IsMatrixExpression(e) } +// ToExpression converts an interface to an Expression type. +// Returns an error if the input is not a recognized expression type. func ToExpression(e interface{}) (Expression, error) { switch { case IsScalarExpression(e): @@ -131,27 +115,17 @@ func ToExpression(e interface{}) (Expression, error) { ) } -/* -Minus -Description: - - subtracts the current expression from another and returns the resulting expression -*/ +// Minus subtracts one expression (right) from another (left) and returns the resulting expression func Minus(left, right Expression) Expression { return left.Plus( right.Multiply(-1.0), ) } -/* -IsLinear -Description: - - Determines whether an input object is a - valid linear expression. - In math, this means that the polynomial like expression - has a degree less than or equal to 1. -*/ +// IsLinear Determines whether an input object is a +// valid linear expression. +// In math, this means that the polynomial like expression +// has a degree less than or equal to 1. func IsLinear(e Expression) bool { // Input Processing if !IsPolynomialLike(e) { @@ -163,15 +137,10 @@ func IsLinear(e Expression) bool { return eAsPL.Degree() <= 1 } -/* -IsQuadratic -Description: - - Determines whether or not an input object is a - valid Quadratic Expression. - In math, this means that the polynomial like expression - has a degree less than or equal to 2. -*/ +// IsQuadratic Determines whether or not an input object is a +// valid Quadratic Expression. +// In math, this means that the polynomial like expression +// has a degree less than or equal to 2. func IsQuadratic(e Expression) bool { // Input Processing if !IsPolynomialLike(e) { @@ -183,12 +152,7 @@ func IsQuadratic(e Expression) bool { return eAsPL.Degree() <= 2 } -/* -HStack -Description: - - Stacks the input expressions horizontally. -*/ +// HStack Stacks the input expressions horizontally. func HStack(eIn ...Expression) Expression { // Input Checking @@ -235,12 +199,7 @@ func HStack(eIn ...Expression) Expression { return ConcretizeExpression(result) } -/* -VStack -Description: - - Stacks the input expressions vertically. -*/ +// VStack Stacks the input expressions vertically. func VStack(eIn ...Expression) Expression { // Input Checking @@ -283,12 +242,7 @@ func VStack(eIn ...Expression) Expression { return ConcretizeExpression(result) } -/* -ConcretizeExpression -Description: - - Converts the input expression to a valid type that implements "Expression". -*/ +// ConcretizeExpression Converts the input expression to a valid type that implements "Expression". func ConcretizeExpression(e interface{}) Expression { // Input Processing diff --git a/symbolic/matrix_constraint.go b/symbolic/matrix_constraint.go index c906382..f46a70e 100644 --- a/symbolic/matrix_constraint.go +++ b/symbolic/matrix_constraint.go @@ -6,44 +6,32 @@ import ( "github.com/MatProGo-dev/SymbolicMath.go/smErrors" ) -/* -matrix_constraint.go -Description: - Functions related to the matrix constraint object. -*/ - +// MatrixConstraint is an object that defines mathematical constraints between two matrices. +// This should implement the Constraint interface. type MatrixConstraint struct { LeftHandSide MatrixExpression RightHandSide MatrixExpression Sense ConstrSense } +// Left returns the left-hand side expression of the matrix constraint. func (mc MatrixConstraint) Left() Expression { return mc.LeftHandSide } +// Right returns the right-hand side expression of the matrix constraint. func (mc MatrixConstraint) Right() Expression { return mc.RightHandSide } -/* -ConstrSense -Description: - - Returns the sense of the constraint. -*/ +// ConstrSense Returns the sense of the constraint. func (mc MatrixConstraint) ConstrSense() ConstrSense { return mc.Sense } -/* -Check -Description: - - Verifies that: - - The left and right hand sides have matching dimensions, - - The sense is valid, (i.e., it is from the set of allowable senses defined in ConstrSense. -*/ +// Check Verifies that: +// - The left and right hand sides have matching dimensions, +// - The sense is valid, (i.e., it is from the set of allowable senses defined in ConstrSense. func (mc MatrixConstraint) Check() error { // Input Processing // Check that the left and right hand sides are well formed. @@ -92,13 +80,8 @@ func (mc MatrixConstraint) Check() error { return nil } -/* -Dims -Description: - - The dimension of the matrix constraint (ideally this should be the same as the dimensions - of the left and right hand sides). -*/ +// Dims The dimension of the matrix constraint (ideally this should be the same as the dimensions +// of the left and right hand sides). func (mc MatrixConstraint) Dims() []int { err := mc.Check() if err != nil { @@ -110,12 +93,7 @@ func (mc MatrixConstraint) Dims() []int { } -/* -AtVec -Description: - - Retrieves the constraint formed by one element of the "vector" constraint. -*/ +// At retrieves the scalar constraint formed by the element at row ii and column jj of the matrix constraint. func (mc MatrixConstraint) At(ii, jj int) ScalarConstraint { // Input Processing err := mc.Check() @@ -136,23 +114,13 @@ func (mc MatrixConstraint) At(ii, jj int) ScalarConstraint { return ScalarConstraint{lhsAtIIJJ, rhsAtIIJJ, mc.Sense} } -/* -IsLinear -Description: - - Describes whether a given matrix constraint is - linear or not. -*/ +// IsLinear Describes whether a given matrix constraint is +// linear or not. func (mc MatrixConstraint) IsLinear() bool { return IsLinear(mc.RightHandSide) && IsLinear(mc.LeftHandSide) } -/* -Substitute -Description: - - Substitutes the variable vIn with the scalar expression seIn -*/ +// Substitute Substitutes the variable vIn with the scalar expression seIn func (mc MatrixConstraint) Substitute(vIn Variable, seIn ScalarExpression) Constraint { // Check that the constraint is well formed. err := mc.Check() @@ -169,13 +137,8 @@ func (mc MatrixConstraint) Substitute(vIn Variable, seIn ScalarExpression) Const return MatrixConstraint{newLHS, newRHS, mc.Sense} } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the map with the corresponding expressions - in the given scalar constraint. -*/ +// SubstituteAccordingTo Substitutes the variables in the map with the corresponding expressions +// in the given scalar constraint. func (mc MatrixConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) Constraint { // Check that the constraint is well formed. err := mc.Check() @@ -192,12 +155,7 @@ func (mc MatrixConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) return MatrixConstraint{newLHS, newRHS, mc.Sense} } -/* -AsSimplifiedConstraint -Description: - - Simplifies the constraint by moving all variables to the left hand side and the constants to the right. -*/ +// AsSimplifiedConstraint Simplifies the constraint by moving all variables to the left hand side and the constants to the right. func (mc MatrixConstraint) AsSimplifiedConstraint() Constraint { // Create Left Hand side of all of the expressions var newLHS Expression = mc.LeftHandSide.Minus(mc.LeftHandSide.Constant()) @@ -218,22 +176,12 @@ func (mc MatrixConstraint) AsSimplifiedConstraint() Constraint { } } -/* -Variables -Description: - - Returns a slice of all the variables in the constraint. -*/ +// Variables Returns a slice of all the variables in the constraint. func (mc MatrixConstraint) Variables() []Variable { return VariablesInThisConstraint(mc) } -/* -ImpliesThisIsAlsoSatisfied -Description: - - Returns true if this constraint implies that the other constraint is also satisfied. -*/ +// ImpliesThisIsAlsoSatisfied Returns true if this constraint implies that the other constraint is also satisfied. func (mc MatrixConstraint) ImpliesThisIsAlsoSatisfied(other Constraint) bool { // Input Processing err := mc.Check() diff --git a/symbolic/matrix_expression.go b/symbolic/matrix_expression.go index 7ea7f4c..bc47294 100644 --- a/symbolic/matrix_expression.go +++ b/symbolic/matrix_expression.go @@ -7,12 +7,8 @@ import ( "gonum.org/v1/gonum/mat" ) -/* - matrix_expression.go - Description: - -*/ - +// MatrixExpression is a mathematical expression that is shaped like a matrix (i.e., with rows and columns). +// This object is an interface for matrix expressions, and so is implemented by other structs in Go (e.g., VariableMatrix). type MatrixExpression interface { // Check returns an error if the expression is not initialized properly Check() error @@ -84,12 +80,7 @@ type MatrixExpression interface { AsSimplifiedExpression() Expression } -/* -IsMatrixExpression -Description: - - Determines whether or not an input object is a valid "VectorExpression" according to MatProInterface. -*/ +// IsMatrixExpression Determines whether or not an input object is a valid "VectorExpression" according to SymbolicMath.go. func IsMatrixExpression(e interface{}) bool { // Check each type switch e.(type) { @@ -111,12 +102,7 @@ func IsMatrixExpression(e interface{}) bool { } } -/* -ToMatrixExpression -Description: - - Converts the input expression to a valid type that implements "VectorExpression". -*/ +// ToMatrixExpression Converts the input expression to a valid type that implements "MatrixExpression". func ToMatrixExpression(e interface{}) (MatrixExpression, error) { // Input Processing if !IsMatrixExpression(e) { @@ -149,23 +135,13 @@ func ToMatrixExpression(e interface{}) (MatrixExpression, error) { } } -/* -IsSquare -Description: - - Determines whether the input matrix expression is square. -*/ +// IsSquare Determines whether the input matrix expression is square. func IsSquare(e MatrixExpression) bool { dims := e.Dims() return dims[0] == dims[1] } -/* -MatrixPowerTemplate -Description: - - Template for the matrix power function. -*/ +// MatrixPowerTemplate template which can easily compute the exponential of an input matrix. Useful, for all MatrixExpression's Power() method (they are required to implement this). func MatrixPowerTemplate(me MatrixExpression, exponent int) MatrixExpression { // Input Processing err := me.Check() @@ -193,12 +169,8 @@ func MatrixPowerTemplate(me MatrixExpression, exponent int) MatrixExpression { return out } -/* -MatrixMultiplyTemplate -Description: - - Template for the matrix multiply function. -*/ +// MatrixMultiplyTemplate is a function that can compute the multiplication of two matrix objects. Any object that implements MatrixExpression can be used in this function to compute products. +// This is also heavily used across all matrix objects because they are required to implement Multiply. func MatrixMultiplyTemplate(left MatrixExpression, right MatrixExpression) Expression { // Input Processing err := left.Check() @@ -255,12 +227,8 @@ func MatrixMultiplyTemplate(left MatrixExpression, right MatrixExpression) Expre return ConcretizeExpression(out) } -/* -MatrixPlusTemplate -Description: - - Template for the matrix plus function. -*/ +// MatrixPlusTemplate is a function that can compute the addition of two matrix objects. Any object that implements MatrixExpression can be used in this function to compute sums. +// This is also heavily used across all matrix objects because they are required to implement Plus(). func MatrixPlusTemplate(left MatrixExpression, right MatrixExpression) MatrixExpression { // Input Processing err := left.Check() @@ -300,12 +268,8 @@ func MatrixPlusTemplate(left MatrixExpression, right MatrixExpression) MatrixExp return ConcretizeMatrixExpression(out) } -/* -MatrixSubstituteTemplate -Description: - - Template for the matrix substitute function. -*/ +// MatrixSubstituteTemplate is a function that can compute the substitution of a variable with a scalar expression into a matrix object. Any object that implements MatrixExpression can be used in this function to compute substitutions. +// This is also heavily used across all matrix objects because they are required to implement SubstituteWith (or related) methods. func MatrixSubstituteTemplate(me MatrixExpression, vIn Variable, seIn ScalarExpression) MatrixExpression { // Input Processing err := me.Check() @@ -336,12 +300,7 @@ func MatrixSubstituteTemplate(me MatrixExpression, vIn Variable, seIn ScalarExpr return ConcretizeMatrixExpression(out) } -/* -ConcretizeMatrixExpression -Description: - - Converts the input expression to a valid type that implements "MatrixExpression". -*/ +// ConcretizeMatrixExpression Converts the input expression to a valid type that implements "MatrixExpression". func ConcretizeMatrixExpression(sliceIn [][]ScalarExpression) MatrixExpression { // Input Processing // - Check that the input slice is not empty diff --git a/symbolic/monomial.go b/symbolic/monomial.go index ae7a026..52acee9 100644 --- a/symbolic/monomial.go +++ b/symbolic/monomial.go @@ -13,21 +13,17 @@ Description: This file defines the function associated with the Monomial object. */ -/* -Type Definition -*/ +// Monomial Type Definition type Monomial struct { Coefficient float64 Exponents []int VariableFactors []Variable } -/* -Check -Description: - - This function checks that the monomial is valid. -*/ +// Check verifies that: +// - The number of degrees in the monomial matches the number of variables in the monomial. +// +// TODO: Perhaps we should check if each of the Variables is well-defined with `Check`? func (m Monomial) Check() error { // Check that the number of degrees matches the number of variables if len(m.Exponents) != len(m.VariableFactors) { @@ -41,32 +37,18 @@ func (m Monomial) Check() error { return nil } -/* -Variables -Description: - - Returns the variables in the monomial. -*/ +// Variables returns the unique variables in the monomial. +// TODO(Kwesi): Add a unique-ness check. func (m Monomial) Variables() []Variable { return m.VariableFactors } -/* -Dims -Description: - - Returns the dimensions of the monomial. (It is a scalar, so this is [1,1]) -*/ +// Dims Returns the dimensions of the monomial. (It is a scalar, so this is [1,1]) func (m Monomial) Dims() []int { return []int{1, 1} } -/* -Plus -Description: - - Multiplication of the monomial with another expression. -*/ +// Plus return the sum of the monomial with another expression. func (m Monomial) Plus(e interface{}) Expression { // Input Processing err := m.Check() @@ -135,12 +117,7 @@ func (m Monomial) Plus(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - Subtraction of the monomial with another expression. -*/ +// Minus returns the difference between a monomial and another expression. func (m Monomial) Minus(e interface{}) Expression { // Input Processing err := m.Check() @@ -174,12 +151,7 @@ func (m Monomial) Minus(e interface{}) Expression { ) } -/* -Multiply -Description: - - Defines the multiplication operation between a monomial and another expression. -*/ +// Multiply returns the product of the input monomial and another expression. func (m Monomial) Multiply(e interface{}) Expression { // Input Processing err := m.Check() @@ -263,12 +235,7 @@ func (m Monomial) Multiply(e interface{}) Expression { ) } -/* -Transpose -Description: - - Transposes the scalar monomial and returns it. (This is the same as simply copying the monomial.) -*/ +// Transpose Transposes the scalar monomial and returns it. (This is the same as simply copying the monomial.) func (m Monomial) Transpose() Expression { // Input Processing err := m.Check() @@ -279,46 +246,28 @@ func (m Monomial) Transpose() Expression { return m } -/* -LessEq -Description: - - Returns a constraint between a monomial being less than an - expression. -*/ +// LessEq returns a less than equal constraint between the current monomial (on the left) and +// another expression (on the right). func (m Monomial) LessEq(rightIn interface{}) Constraint { return m.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Returns a constraint between a monomial being greater than an - expression. -*/ +// GreaterEq returns a "greater than or equal to" constraint between an input monomial and +// another expression. +// c1 := m1.GreaterEq(e2) defines the constraint c1 as the constraint expressing monomial 1 is "greater than or equal to expression e2. func (m Monomial) GreaterEq(rightIn interface{}) Constraint { return m.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - Returns a constraint between a monomial being equal to an - expression. -*/ +// Eq returns the equality constraint between the input monomial and +// another expression. func (m Monomial) Eq(rightIn interface{}) Constraint { return m.Comparison(rightIn, SenseEqual) } -/* -Comparison -Description: - - Base method for creating constraints as comparisons between - two different expressions according to a sense. -*/ +// Comparison returns the "comparison constraint" between the input monomial and another expression. +// The type of comparison (for example, GreaterThanOrEqual) is provided. +// Usually, we recommend using the convenience methods instead (for example, GreaterEq(), Eq(), etc.) instead of this one. func (m Monomial) Comparison(rhsIn interface{}, sense ConstrSense) Constraint { // Input Processing err := m.Check() @@ -366,13 +315,8 @@ func (m Monomial) Comparison(rhsIn interface{}, sense ConstrSense) Constraint { ) } -/* -Constant -Description: - - Returns the constant component in the scalar monomial. - This should be zero unless there are no variables present. Then it will be the coefficient. -*/ +// Constant Returns the constant component in the scalar monomial. +// This should be zero unless there are no variables present. Then it will be the coefficient. func (m Monomial) Constant() float64 { if len(m.VariableFactors) == 0 { return m.Coefficient @@ -381,12 +325,8 @@ func (m Monomial) Constant() float64 { } } -/* -LinearCoeffs -Description: - - Returns the coefficients of the linear terms in the monomial. -*/ +// LinearCoeff returns the coefficients of the linear terms in the monomial. +// If the monomial is not linear, then this will return a vector of zeros. func (m Monomial) LinearCoeff(wrt ...[]Variable) mat.VecDense { // Input Processing err := m.Check() @@ -426,12 +366,7 @@ func (m Monomial) LinearCoeff(wrt ...[]Variable) mat.VecDense { return linearCoeffs } -/* -IsConstant -Description: - - Returns true if the monomial defines a constant. -*/ +// IsConstant Returns true if the monomial defines a constant. func (m Monomial) IsConstant() bool { // Input Checking err := m.Check() @@ -443,12 +378,7 @@ func (m Monomial) IsConstant() bool { return len(m.VariableFactors) == 0 } -/* -IsZero -Description: - - Returns true if the monomial defines the constant zero. -*/ +// IsZero Returns true if the monomial defines the constant zero. func (m Monomial) IsZero() bool { // Input Checking err := m.Check() @@ -460,13 +390,8 @@ func (m Monomial) IsZero() bool { return m.Coefficient == 0.0 } -/* -IsDegreeOneContainingVariable -Description: - - Returns true if the monomial defines an expression containing only the - variable v. -*/ +// IsDegreeOneContainingVariable Returns true if the monomial defines an expression containing only the +// variable v. func (m Monomial) IsDegreeOneContainingVariable(v Variable) bool { // Input Checking err := m.Check() @@ -496,12 +421,7 @@ func (m Monomial) IsDegreeOneContainingVariable(v Variable) bool { } } -/* -IsVariable -Description: - - Returns true if the monomial defines the variable v. -*/ +// IsVariable Returns true if the monomial defines the variable v. func (m Monomial) IsVariable(v Variable) bool { // Input Checking err := m.Check() @@ -519,13 +439,8 @@ func (m Monomial) IsVariable(v Variable) bool { return m.IsDegreeOneContainingVariable(v) && (m.Coefficient == 1.0) } -/* -MatchesFormOf -Description: - - Returns true if the monomial matches the form of the input monomial. - (in other words if the input monomial has the same variables and degrees as the input monomial.) -*/ +// MatchesFormOf Returns true if the monomial matches the form of the input monomial. +// (in other words if the input monomial has the same variables and degrees as the input monomial.) func (m Monomial) MatchesFormOf(mIn Monomial) bool { // Input Checking err := m.Check() @@ -561,16 +476,11 @@ func (m Monomial) MatchesFormOf(mIn Monomial) bool { return true } -/* -DerivativeWrt -Description: - - This function returns the derivative of the monomial with respect to the input - variable vIn. If the monomial does not contain the variable vIn, then the - derivative is zero. - If the monomial does contain the variable vIn, then the derivative is the monomial - with a decreased degree of vIn and a coefficient equal to the original coefficient. -*/ +// DerivativeWrt This function returns the derivative of the monomial with respect to the input +// variable vIn. If the monomial does not contain the variable vIn, then the +// derivative is zero. +// If the monomial does contain the variable vIn, then the derivative is the monomial +// with a decreased degree of vIn and a coefficient equal to the original coefficient. func (m Monomial) DerivativeWrt(vIn Variable) Expression { // Input Processing err := m.Check() @@ -617,12 +527,7 @@ func (m Monomial) DerivativeWrt(vIn Variable) Expression { } } -/* -Degree -Description: - - Returns the degree of the monomial. -*/ +// Degree Returns the degree of the monomial. func (m Monomial) Degree() int { // Input Processing err := m.Check() @@ -640,12 +545,7 @@ func (m Monomial) Degree() int { return degree } -/* -ToPolynomial -Description: - - Creates a copy of the monomial m as a polynomial. -*/ +// ToPolynomial Creates a copy of the monomial m as a polynomial. func (m Monomial) ToPolynomial() Polynomial { // Copy Values mCopy := m.Copy() @@ -656,13 +556,8 @@ func (m Monomial) ToPolynomial() Polynomial { } } -/* -ToVariable -Description: - - Converts the monomial to a variable if it is a variable. - If the monomial is not a variable, then this function panics. -*/ +// ToVariable Converts the monomial to a variable if it is a variable. +// If the monomial is not a variable, then this function panics. func (m Monomial) ToVariable() Variable { // Input Processing err := m.Check() @@ -684,12 +579,7 @@ func (m Monomial) ToVariable() Variable { } } -/* -String -Description: - - Returns a string representation of the monomial. -*/ +// String Returns a string representation of the monomial. func (m Monomial) String() string { // Input Processing err := m.Check() @@ -721,12 +611,7 @@ func (m Monomial) String() string { return monomialString } -/* -Copy -Description: - - Returns a copy of the monomial. -*/ +// Copy Returns a copy of the monomial. func (m Monomial) Copy() Monomial { // Copy Values mCopy := Monomial{ @@ -741,12 +626,7 @@ func (m Monomial) Copy() Monomial { return mCopy } -/* -Substitute -Description: - - Substitutes all occurrences of variable vIn with the expression eIn. -*/ +// Substitute Substitutes all occurrences of variable vIn with the expression eIn. func (m Monomial) Substitute(vIn Variable, eIn ScalarExpression) Expression { // Input Processing err := m.Check() @@ -784,12 +664,7 @@ func (m Monomial) Substitute(vIn Variable, eIn ScalarExpression) Expression { return prod } -/* -SubstituteAccordingTo -Description: - - Substitutes all occurrences of the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo Substitutes all occurrences of the variables in the map with the corresponding expressions. func (m Monomial) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := m.Check() @@ -817,22 +692,13 @@ func (m Monomial) SubstituteAccordingTo(subMap map[Variable]Expression) Expressi return out } -/* -Power -Description: - - Computes the power of the monomial. -*/ +// Power Computes the power of the monomial. func (m Monomial) Power(exponent int) Expression { return ScalarPowerTemplate(m, exponent) } -/* -At -Description: - - Returns the value at the given row and column index. -*/ +// At Returns the value at the given row and column index. +// Because a Monomial is a scalar, there is only one element the (0,0)-th element. func (m Monomial) At(ii, jj int) ScalarExpression { // Input Processing err := m.Check() @@ -849,21 +715,16 @@ func (m Monomial) At(ii, jj int) ScalarExpression { return m } -/* -AsSimplifiedExpression -Description: - - Returns the simplest form of the expression. - - If the monomial contains no variables, - then it is simply the constant coefficient. (return K(m.Coefficient)) - - If the monomial coefficient is zero, - then it is simply the constant zero. (return K(0)) - - If the monomial contains variables BUT all exponents are zero, - then it is simply the constant zero. (return K(0)) - - If the monomial's coefficient is 1.0 and it contains one variable with degree 1, - then it is simply that variable. (return that variable) - - Otherwise, return the monomial itself. -*/ +// AsSimplifiedExpression Returns the simplest form of the expression. +// - If the monomial contains no variables, +// then it is simply the constant coefficient. (return K(m.Coefficient)) +// - If the monomial coefficient is zero, +// then it is simply the constant zero. (return K(0)) +// - If the monomial contains variables BUT all exponents are zero, +// then it is simply the constant zero. (return K(0)) +// - If the monomial's coefficient is 1.0 and it contains one variable with degree 1, +// then it is simply that variable. (return that variable) +// - Otherwise, return the monomial itself. func (m Monomial) AsSimplifiedExpression() Expression { // Input Processing err := m.Check() diff --git a/symbolic/monomial_matrix.go b/symbolic/monomial_matrix.go index f68981e..d4f263f 100644 --- a/symbolic/monomial_matrix.go +++ b/symbolic/monomial_matrix.go @@ -18,21 +18,17 @@ Description: // Type Definition // =============== +// MonomialMatrix is a matrix of monomials. type MonomialMatrix [][]Monomial // ========= // Functions // ========= -/* -Check -Description: - - Verifies that: - - The matrix has at least one row - - The number of columns is the same in each row. - - Each of the monomials in the matrix are valid. -*/ +// Check Verifies that: +// - The matrix has at least one row +// - The number of columns is the same in each row. +// - Each of the monomials in the matrix are valid. func (mm MonomialMatrix) Check() error { // Check that the matrix has at least one row if len(mm) == 0 { @@ -66,12 +62,8 @@ func (mm MonomialMatrix) Check() error { return nil } -/* -Variables -Description: - - Returns the variables in the matrix. -*/ +// Variables returns the unique variables that are contained in the matrix. +// This collects all variables in all entries of the matrix. func (mm MonomialMatrix) Variables() []Variable { // Input Processing err := mm.Check() @@ -91,12 +83,7 @@ func (mm MonomialMatrix) Variables() []Variable { return UniqueVars(variables) } -/* -Dims -Description: - - Returns the dimensions of the matrix. -*/ +// Dims Returns the dimensions of the matrix. func (mm MonomialMatrix) Dims() []int { err := mm.Check() if err != nil { @@ -106,12 +93,7 @@ func (mm MonomialMatrix) Dims() []int { return []int{len(mm), len(mm[0])} } -/* -Plus -Description: - - Addition of the monomial matrix with another expression. -*/ +// Plus returns the sum of the monomial matrix with another expression. func (mm MonomialMatrix) Plus(e interface{}) Expression { // Input Processing err := mm.Check() @@ -223,12 +205,7 @@ func (mm MonomialMatrix) Plus(e interface{}) Expression { } } -/* -Minus -Description: - - Subtraction of the monomial matrix with another expression. -*/ +// Minus returns the difference between the monomial matrix and another expression. func (mm MonomialMatrix) Minus(e interface{}) Expression { // Input Processing err := mm.Check() @@ -261,12 +238,7 @@ func (mm MonomialMatrix) Minus(e interface{}) Expression { ) } -/* -Multiply -Description: - - Multiplication of the monomial matrix with another expression. -*/ +// Multiply returns the product of the monomial matrix with another expression. func (mm MonomialMatrix) Multiply(e interface{}) Expression { // Input Processing err := mm.Check() @@ -357,12 +329,7 @@ func (mm MonomialMatrix) Multiply(e interface{}) Expression { ) } -/* -Transpose -Description: - - Returns the transpose of the monomial matrix. -*/ +// Transpose Returns the transpose of the monomial matrix. func (mm MonomialMatrix) Transpose() Expression { // Input Processing err := mm.Check() @@ -390,12 +357,7 @@ func (mm MonomialMatrix) Transpose() Expression { return mmOut } -/* -Comparison -Description: - - Compares the monomial matrix to another expression according to the sense `sense`. -*/ +// Comparison Compares the monomial matrix to another expression according to the sense `sense`. func (mm MonomialMatrix) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing err := mm.Check() @@ -466,45 +428,25 @@ func (mm MonomialMatrix) Comparison(rightIn interface{}, sense ConstrSense) Cons ) } -/* -LessEq -Description: - - Returns a less than or equal to (<=) constraint between the - current expression and another. -*/ +// LessEq Returns a less than or equal to (<=) constraint between the +// current expression and another. func (mm MonomialMatrix) LessEq(rightIn interface{}) Constraint { return mm.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Returns a greater than or equal to (>=) constraint between the - current expression and another. -*/ +// GreaterEq Returns a greater than or equal to (>=) constraint between the +// current expression and another. func (mm MonomialMatrix) GreaterEq(rightIn interface{}) Constraint { return mm.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - Returns an equality (==) constraint between the current expression - and another. -*/ +// Eq Returns an equality (==) constraint between the current expression +// and another. func (mm MonomialMatrix) Eq(rightIn interface{}) Constraint { return mm.Comparison(rightIn, SenseEqual) } -/* -DerivativeWrt -Description: - - Returns the derivative of the monomial matrix with respect to the input variable. -*/ +// DerivativeWrt Returns the derivative of the monomial matrix with respect to the input variable. func (mm MonomialMatrix) DerivativeWrt(vIn Variable) Expression { // Input Processing err := mm.Check() @@ -533,12 +475,7 @@ func (mm MonomialMatrix) DerivativeWrt(vIn Variable) Expression { return ConcretizeMatrixExpression(dmm) } -/* -At -Description: - - Returns the (ii,jj)-th value of the monomial matrix. -*/ +// At Returns the (ii,jj)-th value of the monomial matrix. func (mm MonomialMatrix) At(ii, jj int) ScalarExpression { // Input Processing err := mm.Check() @@ -550,12 +487,7 @@ func (mm MonomialMatrix) At(ii, jj int) ScalarExpression { return mm[ii][jj] } -/* -Constant -Description: - - Returns the components of the monomial matrix which are constant-valued. -*/ +// Constant Returns the components of the monomial matrix which are constant-valued. func (mm MonomialMatrix) Constant() mat.Dense { // Input Processing err := mm.Check() @@ -579,12 +511,7 @@ func (mm MonomialMatrix) Constant() mat.Dense { return constant } -/* -String -Description: - - Returns a string representation of the monomial matrix. -*/ +// String Returns a string representation of the monomial matrix. func (mm MonomialMatrix) String() string { // Input Processing err := mm.Check() @@ -614,12 +541,7 @@ func (mm MonomialMatrix) String() string { return out } -/* -Degree -Description: - - Returns the MAXIMUM degree in the monomial matrix. -*/ +// Degree Returns the MAXIMUM degree in the monomial matrix. func (mm MonomialMatrix) Degree() int { // Input Processing err := mm.Check() @@ -642,22 +564,12 @@ func (mm MonomialMatrix) Degree() int { return maxDegree } -/* -Substitute -Description: - - Substitutes the variable v with the expression e in the monomial matrix. -*/ +// Substitute Substitutes the variable v with the expression e in the monomial matrix. func (mm MonomialMatrix) Substitute(v Variable, se ScalarExpression) Expression { return MatrixSubstituteTemplate(mm, v, se) } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the monomial matrix according to the map provided in substitutions. -*/ +// SubstituteAccordingTo Substitutes the variables in the monomial matrix according to the map provided in substitutions. func (mm MonomialMatrix) SubstituteAccordingTo(substitutions map[Variable]Expression) Expression { // Input Processing err := mm.Check() @@ -679,22 +591,12 @@ func (mm MonomialMatrix) SubstituteAccordingTo(substitutions map[Variable]Expres return out } -/* -Power -Description: - - Returns the monomial matrix raised to the power of the input integer. -*/ +// Power Returns the monomial matrix raised to the power of the input integer. func (mm MonomialMatrix) Power(exponent int) Expression { return MatrixPowerTemplate(mm, exponent) } -/* -AsSimplifiedExpression -Description: - - Returns the simplest form of the expression. -*/ +// AsSimplifiedExpression Returns the simplest form of the expression. func (mm MonomialMatrix) AsSimplifiedExpression() Expression { // Input Processing err := mm.Check() diff --git a/symbolic/monomial_vector.go b/symbolic/monomial_vector.go index 65b44a1..f8c8745 100644 --- a/symbolic/monomial_vector.go +++ b/symbolic/monomial_vector.go @@ -18,16 +18,12 @@ Description: // Type Definition // =============== +// MonomialVector is a vector of monomials. type MonomialVector []Monomial -/* -Check -Description: - - This function checks that the monomial vector is valid. - It does this by checking that each of the monomials in the vector are valid. - And by checking that there is a non-zero number of them. -*/ +// Check This function checks that the monomial vector is valid. +// It does this by checking that each of the monomials in the vector are valid. +// And by checking that there is a non-zero number of them. func (mv MonomialVector) Check() error { // Check that the polynomial has at least one monomial if len(mv) == 0 { @@ -46,12 +42,7 @@ func (mv MonomialVector) Check() error { return nil } -/* -Variables -Description: - - Returns the variables in the monomial vector. -*/ +// Variables returns the unique variables that are present anywhere in the monomial vector. func (mv MonomialVector) Variables() []Variable { // Check that the monomial vector is well formed err := mv.Check() @@ -69,32 +60,18 @@ func (mv MonomialVector) Variables() []Variable { return UniqueVars(variables) } -/* -Len -Description: - - Returns the number of monomials in the vector. -*/ +// Len Returns the number of monomials in the vector. func (mv MonomialVector) Len() int { return len(mv) } -/* -Dims -Description: - - Returns the dimensions of the monomial vector. -*/ +// Dims returns the dimensions of the monomial vector. +// Because this is a vector, the dimensions will always be [N, 1]. func (mv MonomialVector) Dims() []int { return []int{mv.Len(), 1} } -/* -Constant -Description: - - Returns the constant component of the monomial vector (if one exists). -*/ +// Constant Returns the constant component of the monomial vector (if one exists). func (mv MonomialVector) Constant() mat.VecDense { // Check that the monomial vector is well formed err := mv.Check() @@ -117,12 +94,7 @@ func (mv MonomialVector) Constant() mat.VecDense { return constant } -/* -Plus -Description: - - This function returns the sum of the monomial vector and the input expression. -*/ +// Plus returns the sum of the monomial vector and the input expression. func (mv MonomialVector) Plus(term1 interface{}) Expression { // Input Processing err := mv.Check() @@ -168,12 +140,7 @@ func (mv MonomialVector) Plus(term1 interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - This function returns the difference of the monomial vector and the input expression. -*/ +// Minus returns the difference of the monomial vector and the input expression. func (mv MonomialVector) Minus(term1 interface{}) Expression { // Input Processing err := mv.Check() @@ -218,12 +185,7 @@ func (mv MonomialVector) Minus(term1 interface{}) Expression { ) } -/* -Multiply -Description: - - This function returns the product of the monomial vector and the input expression. -*/ +// Multiply returns the product of the monomial vector and the input expression. func (mv MonomialVector) Multiply(term1 interface{}) Expression { // Input Processing err := mv.Check() @@ -267,12 +229,7 @@ func (mv MonomialVector) Multiply(term1 interface{}) Expression { } -/* -Transpose -Description: - - This function returns the transpose of the monomial vector. -*/ +// Transpose returns the transpose of the monomial vector. func (mv MonomialVector) Transpose() Expression { // Input Processing err := mv.Check() @@ -291,42 +248,22 @@ func (mv MonomialVector) Transpose() Expression { return mm } -/* -LessEq -Description: - - This function creates a constraint that the monomial vector is less than or equal to the input expression. -*/ +// LessEq returns a constraint that the monomial vector is less than or equal to the input expression. func (mv MonomialVector) LessEq(rightIn interface{}) Constraint { return mv.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - This function creates a constraint that the monomial vector is greater than or equal to the input expression. -*/ +// GreaterEq returns a constraint that the monomial vector is greater than or equal to the input expression. func (mv MonomialVector) GreaterEq(rightIn interface{}) Constraint { return mv.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - This function creates a constraint that the monomial vector is equal to the input expression. -*/ +// Eq returns a constraint that the monomial vector is equal to the input expression. func (mv MonomialVector) Eq(rightIn interface{}) Constraint { return mv.Comparison(rightIn, SenseEqual) } -/* -Comparison -Description: - - This function compares the monomial vector to the input expression in the sense provided by sense. -*/ +// Comparison returns a constraint which compares the monomial vector to the input expression in the sense provided by sense. func (mv MonomialVector) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing err := mv.Check() @@ -394,12 +331,7 @@ func (mv MonomialVector) Comparison(rightIn interface{}, sense ConstrSense) Cons } -/* -DerivativeWrt -Description: - - This function returns the derivative of the monomial vector with respect to the input variable. -*/ +// DerivativeWrt returns the derivative of the monomial vector with respect to the input variable. func (mv MonomialVector) DerivativeWrt(v Variable) Expression { // Input Processing err := mv.Check() @@ -446,17 +378,11 @@ func (mv MonomialVector) DerivativeWrt(v Variable) Expression { } } -/* -At -Description: - - This function returns the value of the monomial vector at the - (ii, jj)-th index. - -Note: - - Because this is a vector, the jj input should always be 0. -*/ +// At This function returns the value of the monomial vector at the +// (ii, jj)-th index. +// Note: +// +// Because this is a vector, the jj input should always be 0. func (mv MonomialVector) At(ii, jj int) ScalarExpression { // Input Processing @@ -476,12 +402,7 @@ func (mv MonomialVector) At(ii, jj int) ScalarExpression { return mv[ii] } -/* -AtVec -Description: - - This function returns the value of the monomial vector at the input vector. -*/ +// AtVec returns the value of the monomial vector at the input vector. func (mv MonomialVector) AtVec(idx int) ScalarExpression { // Input Processing err := mv.Check() @@ -493,12 +414,7 @@ func (mv MonomialVector) AtVec(idx int) ScalarExpression { return mv[idx] } -/* -String -Description: - - This function returns a string representation of the monomial vector. -*/ +// String returns a string representation of the monomial vector. func (mv MonomialVector) String() string { // Input Processing err := mv.Check() @@ -519,12 +435,7 @@ func (mv MonomialVector) String() string { return output } -/* -IsConstant -Description: - - Determines whether or not an input object is a valid "MonomialVector" according to MatProInterface. -*/ +// IsConstant Determines whether or not an input object is a valid "MonomialVector" according to MatProInterface. func (mv MonomialVector) IsConstant() bool { // Input Checking err := mv.Check() @@ -543,12 +454,7 @@ func (mv MonomialVector) IsConstant() bool { return true } -/* -ToPolynomialVector -Description: - - This function converts the input monomial vector to a polynomial vector. -*/ +// ToPolynomialVector converts the input monomial vector to a polynomial vector. func (mv MonomialVector) ToPolynomialVector() PolynomialVector { // Input Checking err := mv.Check() @@ -566,12 +472,7 @@ func (mv MonomialVector) ToPolynomialVector() PolynomialVector { return pv } -/* -Degree -Description: - - Returns the MAXIMUM degree in the monomial vector. -*/ +// Degree Returns the MAXIMUM degree in the monomial vector. func (mv MonomialVector) Degree() int { // Input Processing err := mv.Check() @@ -592,22 +493,12 @@ func (mv MonomialVector) Degree() int { return maxDegree } -/* -Substitute -Description: - - This function substitutes the input variable with the input scalar expression. -*/ +// Substitute substitutes the input variable with the input scalar expression. func (mv MonomialVector) Substitute(vIn Variable, seIn ScalarExpression) Expression { return VectorSubstituteTemplate(mv, vIn, seIn) } -/* -SubstituteAccordingTo -Description: - - This function substitutes all instances of variables in the substitutions map with their corresponding expressions. -*/ +// SubstituteAccordingTo substitutes all instances of variables in the substitutions map with their corresponding expressions. func (mv MonomialVector) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := mv.Check() @@ -629,39 +520,24 @@ func (mv MonomialVector) SubstituteAccordingTo(subMap map[Variable]Expression) E return out } -/* -Power -Description: - - This function raises the monomial vector to the input power. -*/ +// Power raises the monomial vector to the input power. func (mv MonomialVector) Power(exponent int) Expression { return VectorPowerTemplate(mv, exponent) } -/* -LinearCoeff -Description: - - This function retrieves the "linear coefficient" of the monomial vector. - In math, this is extracting the matrix A such that: - - mv' = L * v - - where: - - v is the vector of variables for the monomial vector. - - mv' is the monomial vector mv with ONLY the terms that have degree 1 -*/ +// LinearCoeff This function retrieves the "linear coefficient" of the monomial vector. +// In math, this is extracting the matrix A such that: +// +// mv' = L * v +// +// where: +// - v is the vector of variables for the monomial vector. +// - mv' is the monomial vector mv with ONLY the terms that have degree 1 func (mv MonomialVector) LinearCoeff(wrt ...[]Variable) mat.Dense { return PolynomialLikeVector_SharedLinearCoeffCalc(mv, wrt...) } -/* -AsSimplifiedExpression -Description: - - Returns the simplest form of the expression. -*/ +// AsSimplifiedExpression Returns the simplest form of the expression. func (mv MonomialVector) AsSimplifiedExpression() Expression { // Input Processing err := mv.Check() @@ -684,12 +560,7 @@ func (mv MonomialVector) AsSimplifiedExpression() Expression { return ConcretizeVectorExpression(out) } -/* -ToScalarExpressions -Description: - - Converts the MonomialVector into a slice of ScalarExpression type objects. -*/ +// ToScalarExpressions Converts the MonomialVector into a slice of ScalarExpression type objects. func (mv MonomialVector) ToScalarExpressions() []ScalarExpression { var out []ScalarExpression for _, monomial := range mv { diff --git a/symbolic/polynomial.go b/symbolic/polynomial.go index 3afc27f..56552a2 100644 --- a/symbolic/polynomial.go +++ b/symbolic/polynomial.go @@ -14,21 +14,14 @@ Description: This file defines the function associated with the Polynomial object. */ -/* -Type Definition -*/ +// Polynomial Type Definition type Polynomial struct { Monomials []Monomial } // Member Methods -/* -Check -Description: - - Verifies that all elements of the polynomial are defined correctly. -*/ +// Check Verifies that all elements of the polynomial are defined correctly. func (p Polynomial) Check() error { // Check that the polynomial has at least one monomial if len(p.Monomials) == 0 { @@ -47,12 +40,7 @@ func (p Polynomial) Check() error { return nil } -/* -Variables -Description: - - The unique variables used to define the polynomial. -*/ +// Variables The unique variables used to define the polynomial. func (p Polynomial) Variables() []Variable { var variables []Variable // The variables in the polynomial for _, monomial := range p.Monomials { @@ -61,22 +49,12 @@ func (p Polynomial) Variables() []Variable { return UniqueVars(variables) } -/* -Dims -Description: - - The scalar polynomial should have dimensions [1,1]. -*/ +// Dims The scalar polynomial should have dimensions [1,1]. func (p Polynomial) Dims() []int { return []int{1, 1} } -/* -Copy -Description: - - Returns a deep copy of the polynomial. -*/ +// Copy Returns a deep copy of the polynomial. func (p Polynomial) Copy() Polynomial { out := Polynomial{ Monomials: make([]Monomial, len(p.Monomials)), @@ -85,12 +63,7 @@ func (p Polynomial) Copy() Polynomial { return out } -/* -Plus -Description: - - Defines an addition between the polynomial and another expression. -*/ +// Plus Defines an addition between the polynomial and another expression. func (p Polynomial) Plus(e interface{}) Expression { // Input Processing err := p.Check() @@ -213,12 +186,7 @@ func (p Polynomial) Plus(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - Defines a subtraction between the polynomial and another expression. -*/ +// Minus Defines a subtraction between the polynomial and another expression. func (p Polynomial) Minus(e interface{}) Expression { // Input Processing err := p.Check() @@ -253,13 +221,8 @@ func (p Polynomial) Minus(e interface{}) Expression { ) } -/* -ConstantMonomialIndex -Description: - - Returns the index of the monomial in the polynomial which is a constant. - If none are found, then this returns -1. -*/ +// ConstantMonomialIndex Returns the index of the monomial in the polynomial which is a constant. +// If none are found, then this returns -1. func (p Polynomial) ConstantMonomialIndex() int { // Input Processing err := p.Check() @@ -278,12 +241,7 @@ func (p Polynomial) ConstantMonomialIndex() int { return -1 } -/* -VariableMonomialIndex -Description: - - Returns the index of the monomial which represents the variable given as vIn. -*/ +// VariableMonomialIndex Returns the index of the monomial which represents the variable given as vIn. func (p Polynomial) VariableMonomialIndex(vIn Variable) int { // Input Processing err := p.Check() @@ -307,13 +265,8 @@ func (p Polynomial) VariableMonomialIndex(vIn Variable) int { return -1 } -/* -MonomialIndex -Description: - - Returns the index of the monomial which has the same - degrees and variables as the input monomial mIn. -*/ +// MonomialIndex Returns the index of the monomial which has the same +// degrees and variables as the input monomial mIn. func (p Polynomial) MonomialIndex(mIn Monomial) int { // Input Processing err := p.Check() @@ -337,12 +290,7 @@ func (p Polynomial) MonomialIndex(mIn Monomial) int { return -1 } -/* -Multiply -Description: - - Implements the multiplication operator between a polynomial and another expression. -*/ +// Multiply Implements the multiplication operator between a polynomial and another expression. func (p Polynomial) Multiply(e interface{}) Expression { // Input Processing err := p.Check() @@ -427,12 +375,7 @@ func (p Polynomial) Multiply(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - The transpose operator when applied to a scalar is just the same scalar object. -*/ +// Transpose The transpose operator when applied to a scalar is just the same scalar object. func (p Polynomial) Transpose() Expression { // Input Processing err := p.Check() @@ -443,13 +386,8 @@ func (p Polynomial) Transpose() Expression { return p.Copy() } -/* -Comparison -Description: - - Creates a constraint between the polynomial and another expression - of the sense provided in Sense. -*/ +// Comparison Creates a constraint between the polynomial and another expression +// of the sense provided in Sense. func (p Polynomial) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing err := p.Check() @@ -496,42 +434,22 @@ func (p Polynomial) Comparison(rightIn interface{}, sense ConstrSense) Constrain ) } -/* -LessEq -Description: - - Creates a less than equal constraint between the polynomial and another expression. -*/ +// LessEq Creates a less than equal constraint between the polynomial and another expression. func (p Polynomial) LessEq(rightIn interface{}) Constraint { return p.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Creates a greater than equal constraint between the polynomial and another expression. -*/ +// GreaterEq Creates a greater than equal constraint between the polynomial and another expression. func (p Polynomial) GreaterEq(rightIn interface{}) Constraint { return p.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - Creates an equality constraint between the polynomial and another expression. -*/ +// Eq Creates an equality constraint between the polynomial and another expression. func (p Polynomial) Eq(rightIn interface{}) Constraint { return p.Comparison(rightIn, SenseEqual) } -/* -Constant -Description: - - Retrieves the constant component of the polynomial if there is one. -*/ +// Constant Retrieves the constant component of the polynomial if there is one. func (p Polynomial) Constant() float64 { // Input Processing err := p.Check() @@ -548,14 +466,9 @@ func (p Polynomial) Constant() float64 { } } -/* -Simplify -Description: - - This function simplifies the number of monomials in the polynomial, - by finding the matching terms (i.e., monomials with matching Variables and Exponents) - and combining them. -*/ +// Simplify This function simplifies the number of monomials in the polynomial, +// by finding the matching terms (i.e., monomials with matching Variables and Exponents) +// and combining them. func (p Polynomial) Simplify() Polynomial { // Input Processing err := p.Check() @@ -616,6 +529,8 @@ func (p Polynomial) Simplify() Polynomial { } +// AsSimplifiedExpression returns the simplest form of the polynomial, +// reducing it to a lower-degree expression type when possible. func (p Polynomial) AsSimplifiedExpression() Expression { // Simplify the polynomial pReduced := p.Simplify() @@ -641,12 +556,7 @@ func (p Polynomial) AsSimplifiedExpression() Expression { return pReduced } -/* -DerivativeWrt -Description: - - The derivative of the polynomial with respect to the input variable. -*/ +// DerivativeWrt The derivative of the polynomial with respect to the input variable. func (p Polynomial) DerivativeWrt(vIn Variable) Expression { // Input Processing err := p.Check() @@ -691,12 +601,7 @@ func (p Polynomial) DerivativeWrt(vIn Variable) Expression { return derivative } -/* -Degree -Description: - - The degree of the polynomial is the maximum degree of any of the monomials. -*/ +// Degree The degree of the polynomial is the maximum degree of any of the monomials. func (p Polynomial) Degree() int { // Input Processing err := p.Check() @@ -714,15 +619,10 @@ func (p Polynomial) Degree() int { return degree } -/* -LinearCoeff -Description: - - This function returns a vector describing the coefficients of the linear component - of the polynomial. - The (ii)th element of the vector is the coefficient of the (ii)th variable in the - p.Variables() slice as it appears in the polynomial. -*/ +// LinearCoeff This function returns a vector describing the coefficients of the linear component +// of the polynomial. +// The (ii)th element of the vector is the coefficient of the (ii)th variable in the +// p.Variables() slice as it appears in the polynomial. func (p Polynomial) LinearCoeff(wrt ...[]Variable) mat.VecDense { // Input Processing err := p.Check() @@ -761,13 +661,8 @@ func (p Polynomial) LinearCoeff(wrt ...[]Variable) mat.VecDense { return coeffOut } -/* -IsConstant -Description: - - This method returns true if and only if the polynomial - represented by pv is a constant (i.e., it contains no variables). -*/ +// IsConstant This method returns true if and only if the polynomial +// represented by pv is a constant (i.e., it contains no variables). func (p Polynomial) IsConstant() bool { // Input Processing err := p.Check() @@ -779,12 +674,7 @@ func (p Polynomial) IsConstant() bool { return len(p.Variables()) == 0 } -/* -String -Description: - - This method returns a string representation of the polynomial. -*/ +// String This method returns a string representation of the polynomial. func (p Polynomial) String() string { // Input Processing err := p.Check() @@ -824,12 +714,7 @@ func (p Polynomial) String() string { return polynomialString } -/* -Substitute -Description: - - This method substitutes the variable vIn with the expression eIn. -*/ +// Substitute This method substitutes the variable vIn with the expression eIn. func (p Polynomial) Substitute(vIn Variable, eIn ScalarExpression) Expression { // Input Processing err := p.Check() @@ -857,12 +742,7 @@ func (p Polynomial) Substitute(vIn Variable, eIn ScalarExpression) Expression { return out.AsSimplifiedExpression() } -/* -SubstituteAccordingTo -Description: - - This method substitutes the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo This method substitutes the variables in the map with the corresponding expressions. func (p Polynomial) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := p.Check() @@ -885,26 +765,15 @@ func (p Polynomial) SubstituteAccordingTo(subMap map[Variable]Expression) Expres return out } -/* -Power -Description: - - Computes the power of the constant. -*/ +// Power Computes the power of the constant. func (p Polynomial) Power(exponent int) Expression { return ScalarPowerTemplate(p, exponent) } -/* -At -Description: - - Returns the value at the given row and column index. - -Note: - - For a constant, the indices should always be 0. -*/ +// At Returns the value at the given row and column index. +// Note: +// +// For a constant, the indices should always be 0. func (p Polynomial) At(ii, jj int) ScalarExpression { // Input Processing err := p.Check() diff --git a/symbolic/polynomial_like.go b/symbolic/polynomial_like.go index 4063579..73ae230 100644 --- a/symbolic/polynomial_like.go +++ b/symbolic/polynomial_like.go @@ -4,14 +4,9 @@ import ( "github.com/MatProGo-dev/SymbolicMath.go/smErrors" ) -/* -polynomial_like.go -Description: - - This interface should be implemented by all objects - that are polynomial like (i.e., are linear combinations - of variables (potentially raised to powers) and coefficients). -*/ +// PolynomialLike is an interface that should be implemented by all objects +// that are polynomial like (i.e., are linear combinations +// of variables (potentially raised to powers) and coefficients). type PolynomialLike interface { // NumVars returns the number of variables in the expression Variables() []Variable @@ -77,16 +72,13 @@ type PolynomialLike interface { AsSimplifiedExpression() Expression } -/* -IsExpression -Description: - - Tests whether or not the input variable is one of the expression types. -*/ +// IsPolynomialLike tests whether or not the input variable is one of the expression types. func IsPolynomialLike(e interface{}) bool { return IsPolynomialLikeScalar(e) || IsPolynomialLikeVector(e) || IsPolynomialLikeMatrix(e) } +// ToPolynomialLike converts an interface to a PolynomialLike type. +// Returns an error if the input is not a recognized PolynomialLike type. func ToPolynomialLike(e interface{}) (PolynomialLike, error) { switch { case IsPolynomialLikeScalar(e): diff --git a/symbolic/polynomial_like_matrix.go b/symbolic/polynomial_like_matrix.go index fe21f56..a150aba 100644 --- a/symbolic/polynomial_like_matrix.go +++ b/symbolic/polynomial_like_matrix.go @@ -6,12 +6,7 @@ import ( "gonum.org/v1/gonum/mat" ) -/* - matrix_expression.go - Description: - -*/ - +// PolynomialLikeMatrix defines an interface for polynomial-like matrix expressions. type PolynomialLikeMatrix interface { // Check returns an error if the expression is not initialized properly Check() error @@ -85,12 +80,7 @@ type PolynomialLikeMatrix interface { AsSimplifiedExpression() Expression } -/* -IsPolynomialLikeMatrix -Description: - - Determines whether or not an input object is a valid "VectorExpression" according to MatProInterface. -*/ +// IsPolynomialLikeMatrix Determines whether or not an input object is a valid "VectorExpression" according to MatProInterface. func IsPolynomialLikeMatrix(e interface{}) bool { // Check each type switch e.(type) { @@ -110,12 +100,7 @@ func IsPolynomialLikeMatrix(e interface{}) bool { } } -/* -ToPolynomialLikeMatrix -Description: - - Converts the input expression to a valid type that implements "VectorExpression". -*/ +// ToPolynomialLikeMatrix Converts the input expression to a valid type that implements "VectorExpression". func ToPolynomialLikeMatrix(e interface{}) (PolynomialLikeMatrix, error) { // Input Processing if !IsPolynomialLikeMatrix(e) { diff --git a/symbolic/polynomial_like_scalar.go b/symbolic/polynomial_like_scalar.go index a6afe45..774d67a 100644 --- a/symbolic/polynomial_like_scalar.go +++ b/symbolic/polynomial_like_scalar.go @@ -6,7 +6,7 @@ import ( "gonum.org/v1/gonum/mat" ) -// ScalarExpression represents a linear general expression of the form +// PolynomialLikeScalar represents a linear general expression of the form // c0 * x0 + c1 * x1 + ... + cn * xn + k where ci are coefficients and xi are // variables and k is a constant. This is a base interface that is implemented // by single variables, constants, and general linear expressions. @@ -83,13 +83,8 @@ type PolynomialLikeScalar interface { AsSimplifiedExpression() Expression } -/* -IsPolynomialLikeScalar -Description: - - Determines whether or not an input object is a - valid "PolynomialLikeScalar" according to MatProInterface. -*/ +// IsPolynomialLikeScalar Determines whether or not an input object is a +// valid "PolynomialLikeScalar" according to MatProInterface. func IsPolynomialLikeScalar(e interface{}) bool { // Check each type switch e.(type) { @@ -109,13 +104,8 @@ func IsPolynomialLikeScalar(e interface{}) bool { } } -/* -ToPolynomialLikeScalar -Description: - - Converts the input expression to a valid type that - implements "PolynomialLikeScalar". -*/ +// ToPolynomialLikeScalar Converts the input expression to a valid type that +// implements "PolynomialLikeScalar". func ToPolynomialLikeScalar(e interface{}) (PolynomialLikeScalar, error) { // Input Processing if !IsPolynomialLikeScalar(e) { diff --git a/symbolic/polynomial_like_vector.go b/symbolic/polynomial_like_vector.go index f0eb565..03fafd5 100644 --- a/symbolic/polynomial_like_vector.go +++ b/symbolic/polynomial_like_vector.go @@ -13,16 +13,11 @@ import ( "gonum.org/v1/gonum/mat" ) -/* -PolynomialLikeVector -Description: - - This interface represents any expression written in terms of a - vector of represents a linear general expression of the form - c0 * x0 + c1 * x1 + ... + cn * xn + k where ci are coefficients and xi are - variables and k is a constant. This is a base interface that is implemented - by single variables, constants, and general linear expressions. -*/ +// PolynomialLikeVector This interface represents any expression written in terms of a +// vector of represents a linear general expression of the form +// c0 * x0 + c1 * x1 + ... + cn * xn + k where ci are coefficients and xi are +// variables and k is a constant. This is a base interface that is implemented +// by single variables, constants, and general linear expressions. type PolynomialLikeVector interface { // Check returns an error if the expression is not valid Check() error @@ -102,12 +97,7 @@ type PolynomialLikeVector interface { AsSimplifiedExpression() Expression } -/* -IsPolynomialLikeVector -Description: - - Determines whether or not an input object is a valid "PolynomialLikeVector" according to MatProInterface. -*/ +// IsPolynomialLikeVector Determines whether or not an input object is a valid "PolynomialLikeVector" according to MatProInterface. func IsPolynomialLikeVector(e interface{}) bool { // Check each type switch e.(type) { @@ -127,12 +117,7 @@ func IsPolynomialLikeVector(e interface{}) bool { } } -/* -ToPolynomialLikeVector -Description: - - Converts the input expression to a valid type that implements "PolynomialLikeVector". -*/ +// ToPolynomialLikeVector Converts the input expression to a valid type that implements "PolynomialLikeVector". func ToPolynomialLikeVector(e interface{}) (PolynomialLikeVector, error) { // Input Processing if !IsPolynomialLikeVector(e) { @@ -162,17 +147,12 @@ func ToPolynomialLikeVector(e interface{}) (PolynomialLikeVector, error) { } } -/* -PolynomialLikeVector_SharedLinearCoeffCalc -Description: - - This function retrieves the "linear coefficient" of the monomial vector. - In math, this is extracting the matrix A such that: - - mv = L * v - - where v is the vector of variables for the monomial vector. -*/ +// PolynomialLikeVector_SharedLinearCoeffCalc This function retrieves the "linear coefficient" of the monomial vector. +// In math, this is extracting the matrix A such that: +// +// mv = L * v +// +// where v is the vector of variables for the monomial vector. func PolynomialLikeVector_SharedLinearCoeffCalc(plv PolynomialLikeVector, wrt ...[]Variable) mat.Dense { // Input Processing err := plv.Check() diff --git a/symbolic/polynomial_matrix.go b/symbolic/polynomial_matrix.go index 0d7dfd7..eb53016 100644 --- a/symbolic/polynomial_matrix.go +++ b/symbolic/polynomial_matrix.go @@ -18,21 +18,17 @@ Description: // Type Definition // =============== +// PolynomialMatrix is a matrix of polynomials. type PolynomialMatrix [][]Polynomial // ========= // Functions // ========= -/* -Check -Description: - - Verifies that: - - The matrix has at least one row - - The number of columns is the same in each row. - - Each of the polynomials in the matrix are valid. -*/ +// Check Verifies that: +// - The matrix has at least one row +// - The number of columns is the same in each row. +// - Each of the polynomials in the matrix are valid. func (pm PolynomialMatrix) Check() error { // Check that the matrix has at least one row if len(pm) == 0 { @@ -66,12 +62,7 @@ func (pm PolynomialMatrix) Check() error { return nil } -/* -Variables -Description: - - Returns the variables in the polynomial matrix. -*/ +// Variables Returns the variables in the polynomial matrix. func (pm PolynomialMatrix) Variables() []Variable { err := pm.Check() if err != nil { @@ -88,12 +79,7 @@ func (pm PolynomialMatrix) Variables() []Variable { return UniqueVars(variables) } -/* -Dims -Description: - - Returns the dimensions of the matrix of polynomials. -*/ +// Dims Returns the dimensions of the matrix of polynomials. func (pm PolynomialMatrix) Dims() []int { err := pm.Check() if err != nil { @@ -103,12 +89,7 @@ func (pm PolynomialMatrix) Dims() []int { return []int{len(pm), len(pm[0])} } -/* -Plus -Description: - - Addition of the polynomial matrix with another expression. -*/ +// Plus Addition of the polynomial matrix with another expression. func (pm PolynomialMatrix) Plus(e interface{}) Expression { // Input Processing // - Check that pm is valid @@ -205,13 +186,8 @@ func (pm PolynomialMatrix) Plus(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - Subtracts another expression from the given polynomial matrix - and returns the result. -*/ +// Minus Subtracts another expression from the given polynomial matrix +// and returns the result. func (pm PolynomialMatrix) Minus(e interface{}) Expression { // Input Processing // - Check that pm is valid @@ -249,12 +225,7 @@ func (pm PolynomialMatrix) Minus(e interface{}) Expression { ) } -/* -Multiply -Description: - - Multiplication of the polynomial matrix with another expression. -*/ +// Multiply Multiplication of the polynomial matrix with another expression. func (pm PolynomialMatrix) Multiply(e interface{}) Expression { // Input Processing // - Check that pm is valid @@ -341,12 +312,7 @@ func (pm PolynomialMatrix) Multiply(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - Transposes the polynomial matrix. -*/ +// Transpose Transposes the polynomial matrix. func (pm PolynomialMatrix) Transpose() Expression { // Input Processing // - Check that pm is valid @@ -373,12 +339,7 @@ func (pm PolynomialMatrix) Transpose() Expression { return pmT } -/* -Comparison -Description: - - Compares the polynomial matrix to another expression. -*/ +// Comparison Compares the polynomial matrix to another expression. func (pm PolynomialMatrix) Comparison(e interface{}, sense ConstrSense) Constraint { // Input Checking // - Check that pm is valid @@ -435,46 +396,26 @@ func (pm PolynomialMatrix) Comparison(e interface{}, sense ConstrSense) Constrai } } -/* -LessEq -Description: - - Compares the polynomial matrix to another expression using - the SenseLessThanEqual sense. -*/ +// LessEq Compares the polynomial matrix to another expression using +// the SenseLessThanEqual sense. func (pm PolynomialMatrix) LessEq(e interface{}) Constraint { return pm.Comparison(e, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Compares the polynomial matrix to another expression using - the SenseGreaterThanEqual sense. -*/ +// GreaterEq Compares the polynomial matrix to another expression using +// the SenseGreaterThanEqual sense. func (pm PolynomialMatrix) GreaterEq(e interface{}) Constraint { return pm.Comparison(e, SenseGreaterThanEqual) } -/* -Eq -Description: - - Compares the polynomial matrix to another expression using - the SenseEqual sense. -*/ +// Eq Compares the polynomial matrix to another expression using +// the SenseEqual sense. func (pm PolynomialMatrix) Eq(e interface{}) Constraint { return pm.Comparison(e, SenseEqual) } -/* -DerivativeWrt -Description: - - Returns the derivative of the polynomial matrix with respect to the - input variable. -*/ +// DerivativeWrt Returns the derivative of the polynomial matrix with respect to the +// input variable. func (pm PolynomialMatrix) DerivativeWrt(vIn Variable) Expression { // Input Processing // - Check that pm is valid @@ -503,12 +444,7 @@ func (pm PolynomialMatrix) DerivativeWrt(vIn Variable) Expression { return dpm } -/* -At -Description: - - Returns the (ii, jj)-th element of the polynomial matrix. -*/ +// At Returns the (ii, jj)-th element of the polynomial matrix. func (pm PolynomialMatrix) At(ii int, jj int) ScalarExpression { // Input Processing // - Check that pm is valid @@ -528,13 +464,8 @@ func (pm PolynomialMatrix) At(ii int, jj int) ScalarExpression { return pm[ii][jj] } -/* -Constant -Description: - - Returns the components of the polynomial matrix which are - constant-valued. -*/ +// Constant Returns the components of the polynomial matrix which are +// constant-valued. func (pm PolynomialMatrix) Constant() mat.Dense { // Input Processing // - Check that pm is valid @@ -555,12 +486,7 @@ func (pm PolynomialMatrix) Constant() mat.Dense { return constant } -/* -Simplify -Description: - - Simplifies the polynomial matrix, if possible. -*/ +// Simplify Simplifies the polynomial matrix, if possible. func (pm PolynomialMatrix) Simplify() MatrixExpression { // Constants nRows, nCols := pm.Dims()[0], pm.Dims()[1] @@ -585,16 +511,12 @@ func (pm PolynomialMatrix) Simplify() MatrixExpression { return ConcretizeMatrixExpression(simplified) } +// AsSimplifiedExpression returns the simplest form of the polynomial matrix. func (pm PolynomialMatrix) AsSimplifiedExpression() Expression { return pm.Simplify() } -/* -String -Description: - - Returns a string representation of the polynomial matrix. -*/ +// String Returns a string representation of the polynomial matrix. func (pm PolynomialMatrix) String() string { // Input Processing // - Check that pm is valid @@ -627,13 +549,8 @@ func (pm PolynomialMatrix) String() string { return out } -/* -Degree -Description: - - The degree of the polynomial matrix - is the maximum degree of the entries. -*/ +// Degree The degree of the polynomial matrix +// is the maximum degree of the entries. func (pm PolynomialMatrix) Degree() int { // Input Processing err := pm.Check() @@ -653,22 +570,12 @@ func (pm PolynomialMatrix) Degree() int { return maxDegree } -/* -Substitute -Description: - - Substitutes the variable vIn with the expression eIn in the polynomial matrix. -*/ +// Substitute Substitutes the variable vIn with the expression eIn in the polynomial matrix. func (pm PolynomialMatrix) Substitute(vIn Variable, eIn ScalarExpression) Expression { return MatrixSubstituteTemplate(pm, vIn, eIn) } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the polynomial matrix with the corresponding expressions in the map. -*/ +// SubstituteAccordingTo Substitutes the variables in the polynomial matrix with the corresponding expressions in the map. func (pm PolynomialMatrix) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := pm.Check() @@ -691,12 +598,7 @@ func (pm PolynomialMatrix) SubstituteAccordingTo(subMap map[Variable]Expression) return out } -/* -Power -Description: - - Raises the polynomial matrix to the power of the input integer. -*/ +// Power Raises the polynomial matrix to the power of the input integer. func (pm PolynomialMatrix) Power(exponent int) Expression { return MatrixPowerTemplate(pm, exponent) } diff --git a/symbolic/polynomial_vector.go b/symbolic/polynomial_vector.go index 45dc581..4e4144d 100644 --- a/symbolic/polynomial_vector.go +++ b/symbolic/polynomial_vector.go @@ -7,24 +7,14 @@ import ( "gonum.org/v1/gonum/mat" ) -/* -polynomial_vector.go -Description: - Defines a vector of polynomials. -*/ - +// PolynomialVector defines a vector of polynomials. type PolynomialVector []Polynomial // ========= // Functions // ========= -/* -Check -Description: - - Verifies that each of the polynomials in the vector are valid. -*/ +// Check Verifies that each of the polynomials in the vector are valid. func (pv PolynomialVector) Check() error { // Check that the polynomial has at least one monomial if len(pv) == 0 { @@ -43,12 +33,7 @@ func (pv PolynomialVector) Check() error { return nil } -/* -Length -Description: - - The number of elements in the Polynomial vector. -*/ +// Length The number of elements in the Polynomial vector. func (pv PolynomialVector) Length() int { err := pv.Check() if err != nil { @@ -58,26 +43,15 @@ func (pv PolynomialVector) Length() int { return len(pv) } -/* -Len -Description: - - Mirrors the gonum api for vectors. This extracts the element of the variable vector at the index x. -*/ +// Len Mirrors the gonum api for vectors. This extracts the element of the variable vector at the index x. func (pv PolynomialVector) Len() int { return pv.Length() } -/* -At -Description: - - Returns the polynomial at the (ii,jj) index. - -Note: - - - The jj index should always be 0. -*/ +// At Returns the polynomial at the (ii,jj) index. +// Note: +// +// - The jj index should always be 0. func (pv PolynomialVector) At(ii, jj int) ScalarExpression { // Input Processing err := pv.Check() @@ -94,12 +68,7 @@ func (pv PolynomialVector) At(ii, jj int) ScalarExpression { return pv[ii] } -/* -AtVec -Description: - - Retrieves the polynomial at the index idx. -*/ +// AtVec Retrieves the polynomial at the index idx. func (pv PolynomialVector) AtVec(idx int) ScalarExpression { // Input Checking err := pv.Check() @@ -116,12 +85,7 @@ func (pv PolynomialVector) AtVec(idx int) ScalarExpression { return pv[idx] } -/* -Variables -Description: - - Retrieves the set of all unique variables in the polynomial vector. -*/ +// Variables Retrieves the set of all unique variables in the polynomial vector. func (pv PolynomialVector) Variables() []Variable { var variables []Variable // The variables in the polynomial for _, polynomial := range pv { @@ -130,12 +94,7 @@ func (pv PolynomialVector) Variables() []Variable { return UniqueVars(variables) } -/* -Constant -Description: - - Returns all of the constant components of the polynomial vector. -*/ +// Constant Returns all of the constant components of the polynomial vector. func (pv PolynomialVector) Constant() mat.VecDense { // Input Processing err := pv.Check() @@ -153,24 +112,14 @@ func (pv PolynomialVector) Constant() mat.VecDense { return constant } -/* -LinearCoeff -Description: - - Retrieves the coefficients of the linear terms in the polynomial vector. - The output is a matrix where element (ii,jj) of the matrix describes the coefficient - of variable jj (from pv.Variables()) in the polynomial at index ii. -*/ +// LinearCoeff Retrieves the coefficients of the linear terms in the polynomial vector. +// The output is a matrix where element (ii,jj) of the matrix describes the coefficient +// of variable jj (from pv.Variables()) in the polynomial at index ii. func (pv PolynomialVector) LinearCoeff(wrt ...[]Variable) mat.Dense { return PolynomialLikeVector_SharedLinearCoeffCalc(pv, wrt...) } -/* -Plus -Description: - - Defines an addition between the polynomial vector and another expression. -*/ +// Plus Defines an addition between the polynomial vector and another expression. func (pv PolynomialVector) Plus(e interface{}) Expression { // Input Processing err := pv.Check() @@ -217,12 +166,7 @@ func (pv PolynomialVector) Plus(e interface{}) Expression { } -/* -Minus -Description: - - Defines a subtraction between the polynomial vector and another expression. -*/ +// Minus Defines a subtraction between the polynomial vector and another expression. func (pv PolynomialVector) Minus(e interface{}) Expression { // Input Processing // - Check the polynomial vector @@ -260,12 +204,7 @@ func (pv PolynomialVector) Minus(e interface{}) Expression { ) } -/* -Multiply -Description: - - Computes the product of a polynomial vector and another expression. -*/ +// Multiply Computes the product of a polynomial vector and another expression. func (pv PolynomialVector) Multiply(rightIn interface{}) Expression { // Input Processing err := pv.Check() @@ -323,12 +262,7 @@ func (pv PolynomialVector) Multiply(rightIn interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - Computes the transpose of the polynomial vector. -*/ +// Transpose Computes the transpose of the polynomial vector. func (pv PolynomialVector) Transpose() Expression { // Input Processing err := pv.Check() @@ -345,23 +279,13 @@ func (pv PolynomialVector) Transpose() Expression { return pvT } -/* -Dims -Description: - - Returns the shape of the vector which should always be (pv.Len(), 1). -*/ +// Dims Returns the shape of the vector which should always be (pv.Len(), 1). func (pv PolynomialVector) Dims() []int { return []int{pv.Len(), 1} } -/* -Comparison -Description: - - Creates the vector constraint between the polynomial vector pv and another - expression according to the sense senseIn. -*/ +// Comparison Creates the vector constraint between the polynomial vector pv and another +// expression according to the sense senseIn. func (pv PolynomialVector) Comparison(e interface{}, senseIn ConstrSense) Constraint { // Input Processing err := pv.Check() @@ -435,47 +359,27 @@ func (pv PolynomialVector) Comparison(e interface{}, senseIn ConstrSense) Constr } } -/* -LessEq -Description: - - Returns a vector constraint between pv and the input expression. - Leverages the Comparison method. -*/ +// LessEq Returns a vector constraint between pv and the input expression. +// Leverages the Comparison method. func (pv PolynomialVector) LessEq(e interface{}) Constraint { return pv.Comparison(e, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Returns a vector constraint comparing pv and the input expression according - to the GreaterEq sense. - Leverages the Comparison method. -*/ +// GreaterEq Returns a vector constraint comparing pv and the input expression according +// to the GreaterEq sense. +// Leverages the Comparison method. func (pv PolynomialVector) GreaterEq(e interface{}) Constraint { return pv.Comparison(e, SenseGreaterThanEqual) } -/* -Eq -Description: - - Returns a vector constraint comparing pv and the input expression according - to the Eq sense. - Leverages the Comparison method. -*/ +// Eq Returns a vector constraint comparing pv and the input expression according +// to the Eq sense. +// Leverages the Comparison method. func (pv PolynomialVector) Eq(e interface{}) Constraint { return pv.Comparison(e, SenseEqual) } -/* -DerivativeWrt -Description: - - Returns the derivative of the polynomial vector with respect to the input variable. -*/ +// DerivativeWrt Returns the derivative of the polynomial vector with respect to the input variable. func (pv PolynomialVector) DerivativeWrt(vIn Variable) Expression { // Constants var derivative PolynomialVector = pv @@ -488,12 +392,7 @@ func (pv PolynomialVector) DerivativeWrt(vIn Variable) Expression { return derivative } -/* -IsConstantVector -Description: - - This method returns true if the polynomial vector is constant. -*/ +// IsConstantVector This method returns true if the polynomial vector is constant. func (pv PolynomialVector) IsConstantVector() bool { // Constants var isConstant bool = true @@ -506,12 +405,7 @@ func (pv PolynomialVector) IsConstantVector() bool { return isConstant } -/* -Simplify -Description: - - This method simplifies the polynomial vector. -*/ +// Simplify This method simplifies the polynomial vector. func (pv PolynomialVector) Simplify() VectorExpression { // Input Processing err := pv.Check() @@ -541,16 +435,12 @@ func (pv PolynomialVector) Simplify() VectorExpression { return ConcretizeVectorExpression(simplified) } +// AsSimplifiedExpression returns the simplest form of the polynomial vector. func (pv PolynomialVector) AsSimplifiedExpression() Expression { return pv.Simplify() } -/* -String -Description: - - Returns a string representation of the polynomial vector. -*/ +// String Returns a string representation of the polynomial vector. func (pv PolynomialVector) String() string { // Input Processing err := pv.Check() @@ -570,13 +460,8 @@ func (pv PolynomialVector) String() string { return output } -/* -Degree -Description: - - Returns the maximum degree of any of the entries - in the polynomial vector. -*/ +// Degree Returns the maximum degree of any of the entries +// in the polynomial vector. func (pv PolynomialVector) Degree() int { // Input Processing err := pv.Check() @@ -597,22 +482,12 @@ func (pv PolynomialVector) Degree() int { return maxDegree } -/* -Substitute -Description: - - Substitutes the variable vIn with the expression eIn in the polynomial vector. -*/ +// Substitute Substitutes the variable vIn with the expression eIn in the polynomial vector. func (pv PolynomialVector) Substitute(vIn Variable, eIn ScalarExpression) Expression { return VectorSubstituteTemplate(pv, vIn, eIn) } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the polynomial vector with the expressions in the map. -*/ +// SubstituteAccordingTo Substitutes the variables in the polynomial vector with the expressions in the map. func (pv PolynomialVector) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Checking err := pv.Check() @@ -635,22 +510,12 @@ func (pv PolynomialVector) SubstituteAccordingTo(subMap map[Variable]Expression) return result } -/* -Power -Description: - - Computes the power of the polynomial vector. -*/ +// Power Computes the power of the polynomial vector. func (pv PolynomialVector) Power(exponent int) Expression { return VectorPowerTemplate(pv, exponent) } -/* -ToScalarExpressions -Description: - - Converts the PolynomialVector into a slice of ScalarExpression type objects. -*/ +// ToScalarExpressions Converts the PolynomialVector into a slice of ScalarExpression type objects. func (pv PolynomialVector) ToScalarExpressions() []ScalarExpression { var out []ScalarExpression for _, polynomial := range pv { diff --git a/symbolic/scalar_constraint.go b/symbolic/scalar_constraint.go index d6ea979..312c769 100644 --- a/symbolic/scalar_constraint.go +++ b/symbolic/scalar_constraint.go @@ -16,32 +16,24 @@ type ScalarConstraint struct { Sense ConstrSense } +// Left returns the left-hand side expression of the scalar constraint. func (sc ScalarConstraint) Left() Expression { return sc.LeftHandSide } +// Right returns the right-hand side expression of the scalar constraint. func (sc ScalarConstraint) Right() Expression { return sc.RightHandSide } -/* -IsLinear -Description: - - Describes whether a given scalar constraint is - linear or not. -*/ +// IsLinear Describes whether a given scalar constraint is +// linear or not. func (sc ScalarConstraint) IsLinear() bool { return IsLinear(sc.RightHandSide) && IsLinear(sc.LeftHandSide) } -/* -Simplify -Description: - - Moves all of the variables of the ScalarConstraint to its - left hand side. -*/ +// Simplify Moves all of the variables of the ScalarConstraint to its +// left hand side. func (sc ScalarConstraint) Simplify() ScalarConstraint { // Create LHS newLHS := sc.LeftHandSide @@ -64,22 +56,12 @@ func (sc ScalarConstraint) Simplify() ScalarConstraint { } -/* -ConstrSense -Description: - - Returns the sense of the constraint. -*/ +// ConstrSense Returns the sense of the constraint. func (sc ScalarConstraint) ConstrSense() ConstrSense { return sc.Sense } -/* -Check -Description: - - Checks that the ScalarConstraint is valid. -*/ +// Check Checks that the ScalarConstraint is valid. func (sc ScalarConstraint) Check() error { // Input Processing // Check that the left and right hand sides are well formed. @@ -103,14 +85,9 @@ func (sc ScalarConstraint) Check() error { return nil } -/* -LinearInequalityConstraintRepresentation -Description: - - Returns the linear constraint representation of the scalar constraint. - Returns a tuple of the form (A, b) where A is a vector and b is a constant such that: - A.Dot(x) <= b -*/ +// LinearInequalityConstraintRepresentation Returns the linear constraint representation of the scalar constraint. +// Returns a tuple of the form (A, b) where A is a vector and b is a constant such that: +// A.Dot(x) <= b func (sc ScalarConstraint) LinearInequalityConstraintRepresentation(wrt ...[]Variable) (A mat.VecDense, b float64) { // Check that the constraint is well formed. err := sc.Check() @@ -157,14 +134,9 @@ func (sc ScalarConstraint) LinearInequalityConstraintRepresentation(wrt ...[]Var return A, b } -/* -LinearEqualityConstraintRepresentation -Description: - - Returns the linear constraint representation of the scalar constraint. - Returns a tuple of the form (C, d) where C is a vector and d is a constant such that: - C.Dot(x) == d -*/ +// LinearEqualityConstraintRepresentation Returns the linear constraint representation of the scalar constraint. +// Returns a tuple of the form (C, d) where C is a vector and d is a constant such that: +// C.Dot(x) == d func (sc ScalarConstraint) LinearEqualityConstraintRepresentation(wrt ...[]Variable) (C mat.VecDense, d float64) { // Check that the constraint is well formed. err := sc.Check() @@ -211,13 +183,8 @@ func (sc ScalarConstraint) LinearEqualityConstraintRepresentation(wrt ...[]Varia return C, d } -/* -Substitute -Description: - - Substitutes the variable vIn with the scalar expression seIn in the - given scalar constraint. -*/ +// Substitute Substitutes the variable vIn with the scalar expression seIn in the +// given scalar constraint. func (sc ScalarConstraint) Substitute(vIn Variable, seIn ScalarExpression) Constraint { // Check that the constraint is well formed. err := sc.Check() @@ -239,13 +206,8 @@ func (sc ScalarConstraint) Substitute(vIn Variable, seIn ScalarExpression) Const } } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the map with the corresponding expressions - in the given scalar constraint. -*/ +// SubstituteAccordingTo Substitutes the variables in the map with the corresponding expressions +// in the given scalar constraint. func (sc ScalarConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) Constraint { // Check that the constraint is well formed. err := sc.Check() @@ -267,12 +229,7 @@ func (sc ScalarConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) } } -/* -String -Description: - - Returns a string representation of the scalar constraint. -*/ +// String Returns a string representation of the scalar constraint. func (sc ScalarConstraint) String() string { // Check that the constraint is well formed. err := sc.Check() @@ -284,20 +241,18 @@ func (sc ScalarConstraint) String() string { return sc.LeftHandSide.String() + " " + sc.Sense.String() + " " + sc.RightHandSide.String() } -/* -AsSimplifiedConstraint -Description: - - Simplifies the constraint by moving all variables to the left hand side and the constants to the right. -*/ +// AsSimplifiedConstraint Simplifies the constraint by moving all variables to the left hand side and the constants to the right. func (sc ScalarConstraint) AsSimplifiedConstraint() Constraint { return sc.Simplify() } +// Variables returns all variables appearing in the scalar constraint. func (sc ScalarConstraint) Variables() []Variable { return VariablesInThisConstraint(sc) } +// ScaleBy multiplies both sides of the constraint by the given factor +// and returns the resulting constraint. func (sc ScalarConstraint) ScaleBy(factor float64) Constraint { // Check that the constraint is well formed. err := sc.Check() @@ -329,12 +284,7 @@ func (sc ScalarConstraint) ScaleBy(factor float64) Constraint { } } -/* -ImpliesThisIsAlsoSatisfied -Description: - - Returns true if this constraint implies that the other constraint is also satisfied. -*/ +// ImpliesThisIsAlsoSatisfied Returns true if this constraint implies that the other constraint is also satisfied. func (sc ScalarConstraint) ImpliesThisIsAlsoSatisfied(other Constraint) bool { // Check that the constraint is well formed. err := sc.Check() @@ -442,14 +392,9 @@ func (sc ScalarConstraint) ImpliesThisIsAlsoSatisfied(other Constraint) bool { return false } -/* -IsNonnegativityConstraint -Description: - - Checks to see if the constraint is of the form: - - x >= 0, or - - 0 <= x -*/ +// IsNonnegativityConstraint Checks to see if the constraint is of the form: +// - x >= 0, or +// - 0 <= x func (sc ScalarConstraint) IsNonnegativityConstraint() bool { // Setup err := sc.Check() diff --git a/symbolic/scalar_expression.go b/symbolic/scalar_expression.go index 6a3b7f5..61d81a9 100644 --- a/symbolic/scalar_expression.go +++ b/symbolic/scalar_expression.go @@ -91,13 +91,8 @@ type ScalarExpression interface { // return ScalarLinearExpr{C: c} //} -/* -IsScalarExpression -Description: - - Determines whether or not an input object is a - valid "ScalarExpression" according to MatProInterface. -*/ +// IsScalarExpression Determines whether or not an input object is a +// valid "ScalarExpression" according to MatProInterface. func IsScalarExpression(e interface{}) bool { // Check each type switch e.(type) { @@ -117,13 +112,8 @@ func IsScalarExpression(e interface{}) bool { } } -/* -ToScalarExpression -Description: - - Converts the input expression to a valid type that - implements "ScalarExpression". -*/ +// ToScalarExpression Converts the input expression to a valid type that +// implements "ScalarExpression". func ToScalarExpression(e interface{}) (ScalarExpression, error) { // Input Processing if !IsScalarExpression(e) { @@ -153,12 +143,7 @@ func ToScalarExpression(e interface{}) (ScalarExpression, error) { } } -/* -ScalarPowerTemplate -Description: - - Defines the template for the scalar power operation. -*/ +// ScalarPowerTemplate Defines the template for the scalar power operation. func ScalarPowerTemplate(base ScalarExpression, exponent int) Expression { // Setup diff --git a/symbolic/utils.go b/symbolic/utils.go index 2d4c992..0285edd 100644 --- a/symbolic/utils.go +++ b/symbolic/utils.go @@ -6,14 +6,9 @@ import ( "github.com/MatProGo-dev/SymbolicMath.go/smErrors" ) -/* -FindInSlice -Description: - - Identifies if the input xIn is in the slice sliceIn. - If it is, then this function returns the index such that xIn = sliceIn[index] and no errors. - If it is not, then this function returns the index -1 and the boolean value false. -*/ +// FindInSlice Identifies if the input xIn is in the slice sliceIn. +// If it is, then this function returns the index such that xIn = sliceIn[index] and no errors. +// If it is not, then this function returns the index -1 and the boolean value false. func FindInSlice(xIn interface{}, sliceIn interface{}) (int, error) { // Constants allowedTypes := []string{"string", "int", "uint64", "Variable"} @@ -106,12 +101,7 @@ func FindInSlice(xIn interface{}, sliceIn interface{}) (int, error) { } -/* -Unique -Description: - - Returns the unique list of variables in a slice of uint64's. -*/ +// Unique Returns the unique list of variables in a slice of uint64's. func Unique(listIn []uint64) []uint64 { // Create unique list var uniqueList []uint64 @@ -135,13 +125,8 @@ func Unique(listIn []uint64) []uint64 { return uniqueList } -/* -CheckDimensionsInComparison -Description: - - Verifies that the two objects being compared in a Comparison method (Comparison, LessEq, Eq, GreaterEq) - have the same dimensions. -*/ +// CheckDimensionsInComparison Verifies that the two objects being compared in a Comparison method (Comparison, LessEq, Eq, GreaterEq) +// have the same dimensions. func CheckDimensionsInComparison(left, right Expression, senseIn ConstrSense) error { // Check that the size of columns in left and right agree dimsAreMatched := (left.Dims()[0] == right.Dims()[0]) && (left.Dims()[1] == right.Dims()[1]) @@ -159,15 +144,10 @@ func CheckDimensionsInComparison(left, right Expression, senseIn ConstrSense) er return nil } -/* -CheckSubstitutionMap -Description: - - This function verifies that the input substitution map is valid. i.e., the map should contain: - 1. Valid variables as keys - 2. Valid expressions as values - 3. The values should also be scalar expressions -*/ +// CheckSubstitutionMap This function verifies that the input substitution map is valid. i.e., the map should contain: +// 1. Valid variables as keys +// 2. Valid expressions as values +// 3. The values should also be scalar expressions func CheckSubstitutionMap(subMap map[Variable]Expression) error { var err error // Check each key, value pair in the map diff --git a/symbolic/variable.go b/symbolic/variable.go index ad0a8bd..62089c2 100644 --- a/symbolic/variable.go +++ b/symbolic/variable.go @@ -7,7 +7,7 @@ import ( "gonum.org/v1/gonum/mat" ) -// Var represnts a variable in a optimization problem. The variable is +// Variable represents a variable in an optimization problem. The variable is // identified with an uint64. type Variable struct { ID uint64 @@ -19,12 +19,7 @@ type Variable struct { Environment Environment } -/* -Variables -Description: - - This function returns a slice containing all unique variables in the variable expression v. -*/ +// Variables This function returns a slice containing all unique variables in the variable expression v. func (v Variable) Variables() []Variable { return []Variable{v} } @@ -35,13 +30,8 @@ func (v Variable) Constant() float64 { return 0 } -/* -LinearCoeff -Description: - - Returns the coefficient of the linear term in the expression. For a variable, - this is always a vector containing exactly 1 value of 1.0 all others are zero. -*/ +// LinearCoeff Returns the coefficient of the linear term in the expression. For a variable, +// this is always a vector containing exactly 1 value of 1.0 all others are zero. func (v Variable) LinearCoeff(wrt ...[]Variable) mat.VecDense { // Input Processing err := v.Check() @@ -141,13 +131,8 @@ func (v Variable) Plus(rightIn interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - This function subtracts an expression from the current - variable. -*/ +// Minus This function subtracts an expression from the current +// variable. func (v Variable) Minus(rightIn interface{}) Expression { // Input Processing err := v.Check() @@ -204,16 +189,10 @@ func (v Variable) Eq(rhsIn interface{}) Constraint { return v.Comparison(rhsIn, SenseEqual) } -/* -Comparison -Description: - - This method compares the receiver with expression rhs in the sense provided by sense. - -Usage: - - constr, err := v.Comparison(expr1,SenseGreaterThanEqual) -*/ +// Comparison This method compares the receiver with expression rhs in the sense provided by sense. +// Usage: +// +// constr, err := v.Comparison(expr1,SenseGreaterThanEqual) func (v Variable) Comparison(rhsIn interface{}, sense ConstrSense) Constraint { // Input Processing err := v.Check() @@ -274,13 +253,8 @@ const ( Integer = 'I' ) -/* -UniqueVars -Description: - - This function creates a slice of unique variables from the slice given in - varsIn -*/ +// UniqueVars This function creates a slice of unique variables from the slice given in +// varsIn func UniqueVars(varsIn []Variable) []Variable { // Constants @@ -296,12 +270,7 @@ func UniqueVars(varsIn []Variable) []Variable { } -/* -Multiply -Description: - - multiplies the current expression to another and returns the resulting expression -*/ +// Multiply multiplies the current expression to another and returns the resulting expression func (v Variable) Multiply(rightIn interface{}) Expression { // Input Processing err := v.Check() @@ -381,22 +350,12 @@ func (v Variable) Multiply(rightIn interface{}) Expression { } -/* -Dims -Description: - - Returns the dimension of the Variable object (should be scalar). -*/ +// Dims Returns the dimension of the Variable object (should be scalar). func (v Variable) Dims() []int { return []int{1, 1} } -/* -Check -Description: - - Checks whether the Variable has a sensible initialization. -*/ +// Check Checks whether the Variable has a sensible initialization. func (v Variable) Check() error { // Check that the lower bound is below is the upper bound if v.Lower >= v.Upper { @@ -410,24 +369,18 @@ func (v Variable) Check() error { return nil } +// Transpose returns the variable itself, as the transpose of a scalar is itself. func (v Variable) Transpose() Expression { return v } -/* -NewVariable -Description: -*/ +// NewVariable creates a new continuous variable in the given environment +// (or the default environment if none is provided). func NewVariable(envs ...Environment) Variable { return NewContinuousVariable(envs...) } -/* -NewContinuousVariable -Description: - - Creates a new continuous variable. -*/ +// NewContinuousVariable Creates a new continuous variable. func NewContinuousVariable(envs ...Environment) Variable { // Constants @@ -458,12 +411,7 @@ func NewContinuousVariable(envs ...Environment) Variable { } -/* -NewContinuousVariable -Description: - - Creates a new binary variable. -*/ +// NewBinaryVariable creates a new binary variable. func NewBinaryVariable(envs ...Environment) Variable { // Constants @@ -494,12 +442,7 @@ func NewBinaryVariable(envs ...Environment) Variable { } -/* -ToMonomial -Description: - - Converts the variable into a monomial. -*/ +// ToMonomial Converts the variable into a monomial. func (v Variable) ToMonomial() Monomial { return Monomial{ Coefficient: 1.0, @@ -508,26 +451,16 @@ func (v Variable) ToMonomial() Monomial { } } -/* -ToPolynomial -Description: - - Converts the variable into a monomial and then into a polynomial. -*/ +// ToPolynomial Converts the variable into a monomial and then into a polynomial. func (v Variable) ToPolynomial() Polynomial { return Polynomial{ Monomials: []Monomial{v.ToMonomial()}, } } -/* -DerivativeWrt -Description: - - Computes the derivative of the Variable with respect to vIn. - If vIn is the same as the Variable, then this returns 1.0. Otherwise, it - returns 0.0. -*/ +// DerivativeWrt Computes the derivative of the Variable with respect to vIn. +// If vIn is the same as the Variable, then this returns 1.0. Otherwise, it +// returns 0.0. func (v Variable) DerivativeWrt(vIn Variable) Expression { // Input Processing err := v.Check() @@ -548,32 +481,17 @@ func (v Variable) DerivativeWrt(vIn Variable) Expression { } } -/* -Degree -Description: - - Returns the degree of the variable (which is always 1). -*/ +// Degree Returns the degree of the variable (which is always 1). func (v Variable) Degree() int { return 1 } -/* -String -Description: - - This method returns a string representation of the variable. -*/ +// String This method returns a string representation of the variable. func (v Variable) String() string { return v.Name } -/* -Substitute -Description: - - Substitutes the variable vIn with the expression eIn. -*/ +// Substitute Substitutes the variable vIn with the expression eIn. func (v Variable) Substitute(vIn Variable, seIn ScalarExpression) Expression { // Input Processing err := v.Check() @@ -604,12 +522,7 @@ func (v Variable) Substitute(vIn Variable, seIn ScalarExpression) Expression { } } -/* -SubstituteAccordingTo -Description: - - Substitutes the variable in the map with the corresponding expression. -*/ +// SubstituteAccordingTo Substitutes the variable in the map with the corresponding expression. func (v Variable) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := v.Check() @@ -630,26 +543,15 @@ func (v Variable) SubstituteAccordingTo(subMap map[Variable]Expression) Expressi } } -/* -Power -Description: - - Computes the power of the variable. -*/ +// Power Computes the power of the variable. func (v Variable) Power(exponent int) Expression { return ScalarPowerTemplate(v, exponent) } -/* -At -Description: - - Returns the value at the given row and column index. - -Note: - - For a variable, the row and column index should always be 0. -*/ +// At Returns the value at the given row and column index. +// Note: +// +// For a variable, the row and column index should always be 0. func (v Variable) At(ii, jj int) ScalarExpression { // Input Processing @@ -669,6 +571,8 @@ func (v Variable) At(ii, jj int) ScalarExpression { return v } +// UnionOfVariables returns a slice containing the unique union of all variables +// from the given slices. func UnionOfVariables(varSlices ...[]Variable) []Variable { var allVars []Variable for _, varSlice := range varSlices { @@ -677,12 +581,7 @@ func UnionOfVariables(varSlices ...[]Variable) []Variable { return UniqueVars(allVars) } -/* -AsSimplifiedExpression -Description: - - Simplifies the expression and returns the simplified version. -*/ +// AsSimplifiedExpression Simplifies the expression and returns the simplified version. func (v Variable) AsSimplifiedExpression() Expression { return v } diff --git a/symbolic/variable_matrix.go b/symbolic/variable_matrix.go index 21b2812..f56ae37 100644 --- a/symbolic/variable_matrix.go +++ b/symbolic/variable_matrix.go @@ -18,22 +18,18 @@ Description: // Types // ===== +// VariableMatrix is a matrix of variables. type VariableMatrix [][]Variable // ======= // Methods // ======= -/* -Check -Description: - - This method is used to make sure that the variable matrix is well-defined. - It checks: - - That the matrix is not empty. - - That all of the rows have the same number of columns. - - That all of the variables are well-defined. -*/ +// Check This method is used to make sure that the variable matrix is well-defined. +// It checks: +// - That the matrix is not empty. +// - That all of the rows have the same number of columns. +// - That all of the variables are well-defined. func (vm VariableMatrix) Check() error { // Input Processing @@ -75,12 +71,7 @@ func (vm VariableMatrix) Check() error { return nil } -/* -Variables -Description: - - This function returns the list of variables in the matrix. -*/ +// Variables This function returns the list of variables in the matrix. func (vm VariableMatrix) Variables() []Variable { // Input Processing err := vm.Check() @@ -97,12 +88,7 @@ func (vm VariableMatrix) Variables() []Variable { return UniqueVars(variables) } -/* -Dims -Description: - - This function returns the dimensions of the variable matrix. -*/ +// Dims This function returns the dimensions of the variable matrix. func (vm VariableMatrix) Dims() []int { // Input Processing err := vm.Check() @@ -114,12 +100,7 @@ func (vm VariableMatrix) Dims() []int { return []int{len(vm), len(vm[0])} } -/* -Plus -Description: - - This function adds two variable matrices together. -*/ +// Plus This function adds two variable matrices together. func (vm VariableMatrix) Plus(e interface{}) Expression { // Input Processing err := vm.Check() @@ -178,12 +159,7 @@ func (vm VariableMatrix) Plus(e interface{}) Expression { ) } -/* -Minus -Description: - - This function subtracts a variable matrix from another term. -*/ +// Minus This function subtracts a variable matrix from another term. func (vm VariableMatrix) Minus(e interface{}) Expression { // Input Processing // - Check the variable matrix is well-defined @@ -235,12 +211,7 @@ func (vm VariableMatrix) Minus(e interface{}) Expression { } -/* -Multiply -Description: - - This function multiplies a variable matrix by another term. -*/ +// Multiply This function multiplies a variable matrix by another term. func (vm VariableMatrix) Multiply(e interface{}) Expression { // Input Processing err := vm.Check() @@ -339,12 +310,7 @@ func (vm VariableMatrix) Multiply(e interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Transpose -Description: - - This function returns the transpose of the variable matrix. -*/ +// Transpose This function returns the transpose of the variable matrix. func (vm VariableMatrix) Transpose() Expression { // Input Processing err := vm.Check() @@ -369,12 +335,7 @@ func (vm VariableMatrix) Transpose() Expression { return vmOut } -/* -Comparison -Description: - - This function compares the variable matrix to another expression. -*/ +// Comparison This function compares the variable matrix to another expression. func (vm VariableMatrix) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing err := vm.Check() @@ -431,46 +392,26 @@ func (vm VariableMatrix) Comparison(rightIn interface{}, sense ConstrSense) Cons ) } -/* -LessEq -Description: - - Returns a less than or equal to (<=) constraint between - the VariableMatrix and another expression. -*/ +// LessEq Returns a less than or equal to (<=) constraint between +// the VariableMatrix and another expression. func (vm VariableMatrix) LessEq(rightIn interface{}) Constraint { return vm.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - Returns a greater than or equal to (>=) constraint between - the VariableMatrix and another expression. -*/ +// GreaterEq Returns a greater than or equal to (>=) constraint between +// the VariableMatrix and another expression. func (vm VariableMatrix) GreaterEq(rightIn interface{}) Constraint { return vm.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - Returns an equality (==) constraint between - the VariableMatrix and another expression. -*/ +// Eq Returns an equality (==) constraint between +// the VariableMatrix and another expression. func (vm VariableMatrix) Eq(rightIn interface{}) Constraint { return vm.Comparison(rightIn, SenseEqual) } -/* -DerivativeWrt -Description: - - This function returns the derivative of the variable matrix - with respect to a given variable. -*/ +// DerivativeWrt This function returns the derivative of the variable matrix +// with respect to a given variable. func (vm VariableMatrix) DerivativeWrt(v Variable) Expression { // Input Processing err := vm.Check() @@ -497,12 +438,7 @@ func (vm VariableMatrix) DerivativeWrt(v Variable) Expression { return kmOut } -/* -At -Description: - - This function returns the element of the variable matrix at the given indices. -*/ +// At This function returns the element of the variable matrix at the given indices. func (vm VariableMatrix) At(ii, jj int) ScalarExpression { // Input Processing err := vm.Check() @@ -514,23 +450,13 @@ func (vm VariableMatrix) At(ii, jj int) ScalarExpression { return vm[ii][jj] } -/* -Constant -Description: - - This function returns the constant value in the variable matrix. - this should always be zero. -*/ +// Constant This function returns the constant value in the variable matrix. +// this should always be zero. func (vm VariableMatrix) Constant() mat.Dense { return ZerosMatrix(vm.Dims()[0], vm.Dims()[1]) } -/* -String -Description: - - This function returns a string representation of the variable matrix. -*/ +// String This function returns a string representation of the variable matrix. func (vm VariableMatrix) String() string { // Input Processing err := vm.Check() @@ -557,25 +483,15 @@ func (vm VariableMatrix) String() string { return out } -/* -NewVariableMatrix -Description: - - This function creates a new variable matrix - and properly initializes each element in it. -*/ +// NewVariableMatrix This function creates a new variable matrix +// and properly initializes each element in it. func NewVariableMatrix(nRows, nCols int, envs ...Environment) VariableMatrix { return NewVariableMatrixClassic(nRows, nCols, envs...) } -/* -NewVariableMatrixClassic -Description: - - This function creates a new variable matrix - and properly initializes each element in it - when given a list of variables. -*/ +// NewVariableMatrixClassic This function creates a new variable matrix +// and properly initializes each element in it +// when given a list of variables. func NewVariableMatrixClassic(nRows, nCols int, envs ...Environment) VariableMatrix { // Collect an environment if one exists var env Environment @@ -601,12 +517,7 @@ func NewVariableMatrixClassic(nRows, nCols int, envs ...Environment) VariableMat return vmOut } -/* -ToMonomialMatrix -Description: - - This function converts the variable matrix to a monomial matrix. -*/ +// ToMonomialMatrix This function converts the variable matrix to a monomial matrix. func (vm VariableMatrix) ToMonomialMatrix() MonomialMatrix { // Input Processing err := vm.Check() @@ -626,12 +537,7 @@ func (vm VariableMatrix) ToMonomialMatrix() MonomialMatrix { return mmOut } -/* -ToPolynomialMatrix -Description: - - This function converts the variable matrix to a polynomial matrix. -*/ +// ToPolynomialMatrix This function converts the variable matrix to a polynomial matrix. func (vm VariableMatrix) ToPolynomialMatrix() PolynomialMatrix { // Input Processing err := vm.Check() @@ -651,33 +557,18 @@ func (vm VariableMatrix) ToPolynomialMatrix() PolynomialMatrix { return pmOut } -/* -Degree -Description: - - Returns the maximum degree of the vector of - variables (which is always 1). -*/ +// Degree Returns the maximum degree of the vector of +// variables (which is always 1). func (vm VariableMatrix) Degree() int { return 1 } -/* -Substitute -Description: - - This function substitutes the variable vIn with the expression eIn. -*/ +// Substitute This function substitutes the variable vIn with the expression eIn. func (vm VariableMatrix) Substitute(vIn Variable, eIn ScalarExpression) Expression { return MatrixSubstituteTemplate(vm, vIn, eIn) } -/* -SubstituteAccordingTo -Description: - - This function substitutes the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo This function substitutes the variables in the map with the corresponding expressions. func (vm VariableMatrix) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := vm.Check() @@ -700,22 +591,12 @@ func (vm VariableMatrix) SubstituteAccordingTo(subMap map[Variable]Expression) E return out } -/* -Power -Description: - - This function raises the variable matrix to a given power. -*/ +// Power This function raises the variable matrix to a given power. func (vm VariableMatrix) Power(exponent int) Expression { return MatrixPowerTemplate(vm, exponent) } -/* -AsSimplifiedExpression -Description: - - Simplifies the expression and returns the simplified version. -*/ +// AsSimplifiedExpression Simplifies the expression and returns the simplified version. func (vm VariableMatrix) AsSimplifiedExpression() Expression { return vm } diff --git a/symbolic/variable_vector.go b/symbolic/variable_vector.go index 3c83820..4d6e546 100644 --- a/symbolic/variable_vector.go +++ b/symbolic/variable_vector.go @@ -13,48 +13,27 @@ Description: The VariableVector type will represent a */ -/* -VariableVector -Description: - - Represnts a variable in a optimization problem. The variable is -*/ +// VariableVector represents a vector of variables in an optimization problem. type VariableVector []Variable // ========= // Functions // ========= -/* -Length -Description: - - Returns the length of the vector of optimization variables. -*/ +// Length Returns the length of the vector of optimization variables. func (vv VariableVector) Length() int { return len(vv) } -/* -Len -Description: - - This function is created to mirror the GoNum Vector API. Does the same thing as Length. -*/ +// Len This function is created to mirror the GoNum Vector API. Does the same thing as Length. func (vv VariableVector) Len() int { return vv.Length() } -/* -At -Description: - - Returns the variable at the (ii, jj)-th index of the vector. - -Note: - - Because this is a vector, the jj index SHOULD always 0. -*/ +// At Returns the variable at the (ii, jj)-th index of the vector. +// Note: +// +// Because this is a vector, the jj index SHOULD always 0. func (vv VariableVector) At(ii, jj int) ScalarExpression { // Input Checking err := vv.Check() @@ -72,12 +51,7 @@ func (vv VariableVector) At(ii, jj int) ScalarExpression { return vv[ii] } -/* -AtVec -Description: - - Mirrors the gonum api for vectors. This extracts the element of the variable vector at the index x. -*/ +// AtVec Mirrors the gonum api for vectors. This extracts the element of the variable vector at the index x. func (vv VariableVector) AtVec(idx int) ScalarExpression { // Constants @@ -91,45 +65,25 @@ func (vv VariableVector) AtVec(idx int) ScalarExpression { return vv[idx] } -/* -Variables -Description: - - Returns the slice of all variables in the vector. -*/ +// Variables Returns the slice of all variables in the vector. func (vv VariableVector) Variables() []Variable { return UniqueVars(vv) } -/* -Constant -Description: - - Returns an all zeros vector as output from the method. -*/ +// Constant Returns an all zeros vector as output from the method. func (vv VariableVector) Constant() mat.VecDense { zerosOut := ZerosVector(vv.Len()) return zerosOut } -/* -LinearCoeff -Description: - - Returns the matrix which is multiplied by Variables to get the current "expression". - For a single vector, this is an identity matrix. -*/ +// LinearCoeff Returns the matrix which is multiplied by Variables to get the current "expression". +// For a single vector, this is an identity matrix. func (vv VariableVector) LinearCoeff(wrt ...[]Variable) mat.Dense { return PolynomialLikeVector_SharedLinearCoeffCalc(vv, wrt...) } -/* -Plus -Description: - - This member function computes the addition of the receiver vector var with the - incoming vector expression ve. -*/ +// Plus This member function computes the addition of the receiver vector var with the +// incoming vector expression ve. func (vv VariableVector) Plus(rightIn interface{}) Expression { // Constants // vvLen := vv.Len() @@ -181,13 +135,8 @@ func (vv VariableVector) Plus(rightIn interface{}) Expression { return out.AsSimplifiedExpression() } -/* -Minus -Description: - - This function subtracts an expression from the current - variable vector and returns the resulting expression. -*/ +// Minus This function subtracts an expression from the current +// variable vector and returns the resulting expression. func (vv VariableVector) Minus(rightIn interface{}) Expression { // Input Checking // - Check that the receiver is well-defined @@ -225,12 +174,7 @@ func (vv VariableVector) Minus(rightIn interface{}) Expression { ) } -/* -Multiply -Description: - - Multiplication of a VariableVector with another expression. -*/ +// Multiply Multiplication of a VariableVector with another expression. func (vv VariableVector) Multiply(rightIn interface{}) Expression { //Input Processing err := vv.Check() @@ -278,47 +222,27 @@ func (vv VariableVector) Multiply(rightIn interface{}) Expression { } -/* -LessEq -Description: - - This method creates a less than or equal to vector constraint using the receiver as the left hand side and the - input rhs as the right hand side if it is valid. -*/ +// LessEq This method creates a less than or equal to vector constraint using the receiver as the left hand side and the +// input rhs as the right hand side if it is valid. func (vv VariableVector) LessEq(rightIn interface{}) Constraint { return vv.Comparison(rightIn, SenseLessThanEqual) } -/* -GreaterEq -Description: - - This method creates a greater than or equal to vector constraint using the receiver as the left hand side and the - input rhs as the right hand side if it is valid. -*/ +// GreaterEq This method creates a greater than or equal to vector constraint using the receiver as the left hand side and the +// input rhs as the right hand side if it is valid. func (vv VariableVector) GreaterEq(rightIn interface{}) Constraint { return vv.Comparison(rightIn, SenseGreaterThanEqual) } -/* -Eq -Description: - - This method creates an equal to vector constraint using the receiver as the left hand side and the - input rhs as the right hand side if it is valid. -*/ +// Eq This method creates an equal to vector constraint using the receiver as the left hand side and the +// input rhs as the right hand side if it is valid. func (vv VariableVector) Eq(rightIn interface{}) Constraint { return vv.Comparison(rightIn, SenseEqual) } -/* -Comparison -Description: - - This method creates a constraint of type sense between - the receiver (as left hand side) and rhs (as right hand side) if both are valid. -*/ +// Comparison This method creates a constraint of type sense between +// the receiver (as left hand side) and rhs (as right hand side) if both are valid. func (vv VariableVector) Comparison(rightIn interface{}, sense ConstrSense) Constraint { // Input Processing err := vv.Check() @@ -367,6 +291,7 @@ func (vv VariableVector) Comparison(rightIn interface{}, sense ConstrSense) Cons ) } +// Copy returns a new VariableVector with the same variables as the receiver. func (vv VariableVector) Copy() VariableVector { // Constants @@ -381,12 +306,7 @@ func (vv VariableVector) Copy() VariableVector { } -/* -Transpose -Description: - - This method creates the transpose of the current vector and returns it. -*/ +// Transpose This method creates the transpose of the current vector and returns it. func (vv VariableVector) Transpose() Expression { // Input Processing err := vv.Check() @@ -400,22 +320,12 @@ func (vv VariableVector) Transpose() Expression { return vmOut } -/* -Dims -Description: - - Dimensions of the variable vector. -*/ +// Dims Dimensions of the variable vector. func (vv VariableVector) Dims() []int { return []int{vv.Len(), 1} } -/* -Check -Description: - - Checks whether or not the VariableVector has a sensible initialization. -*/ +// Check Checks whether or not the VariableVector has a sensible initialization. func (vv VariableVector) Check() error { // Check that each variable is properly defined for ii, element := range vv { @@ -432,15 +342,10 @@ func (vv VariableVector) Check() error { return nil } -/* -DerivativeWrt -Description: - - This function returns the derivative of the VariableVector with respect to the input variable - vIn, which is a vector where each element: - - is 0 if the variable is not the same as vIn - - is 1 if the variable is the same as vIn -*/ +// DerivativeWrt This function returns the derivative of the VariableVector with respect to the input variable +// vIn, which is a vector where each element: +// - is 0 if the variable is not the same as vIn +// - is 1 if the variable is the same as vIn func (vv VariableVector) DerivativeWrt(vIn Variable) Expression { // Input Processing err := vv.Check() @@ -466,12 +371,7 @@ func (vv VariableVector) DerivativeWrt(vIn Variable) Expression { return VecDenseToKVector(vecOut) } -/* -NewVariableVector -Description: - - Returns a new VariableVector object. -*/ +// NewVariableVector Returns a new VariableVector object. func NewVariableVector(N int, envs ...Environment) VariableVector { // Constants @@ -492,12 +392,7 @@ func NewVariableVector(N int, envs ...Environment) VariableVector { } -/* -String -Description: - - Returns a string representation of the VariableVector. -*/ +// String Returns a string representation of the VariableVector. func (vv VariableVector) String() string { // Input Processing err := vv.Check() @@ -518,12 +413,7 @@ func (vv VariableVector) String() string { return output } -/* -ToMonomialVector -Description: - - This function converts the input expression to a monomial vector. -*/ +// ToMonomialVector This function converts the input expression to a monomial vector. func (vv VariableVector) ToMonomialVector() MonomialVector { // Input Processing err := vv.Check() @@ -542,12 +432,7 @@ func (vv VariableVector) ToMonomialVector() MonomialVector { return out } -/* -ToPolynomialVector -Description: - - This function converts the input expression to a polynomial vector. -*/ +// ToPolynomialVector This function converts the input expression to a polynomial vector. func (vv VariableVector) ToPolynomialVector() PolynomialVector { // Input Processing err := vv.Check() @@ -566,33 +451,18 @@ func (vv VariableVector) ToPolynomialVector() PolynomialVector { return out } -/* -Degree -Description: - - Returns the degree of the vector of variables - (which is always 1). -*/ +// Degree Returns the degree of the vector of variables +// (which is always 1). func (vv VariableVector) Degree() int { return 1 } -/* -Substitute -Description: - - Substitute returns the expression with the variable vIn replaced with the expression eIn -*/ +// Substitute Substitute returns the expression with the variable vIn replaced with the expression eIn func (vv VariableVector) Substitute(vIn Variable, seIn ScalarExpression) Expression { return VectorSubstituteTemplate(vv, vIn, seIn) } -/* -SubstituteAccordingTo -Description: - - Substitute replaces all instances of the variables in the map with the corresponding expressions. -*/ +// SubstituteAccordingTo Substitute replaces all instances of the variables in the map with the corresponding expressions. func (vv VariableVector) SubstituteAccordingTo(subMap map[Variable]Expression) Expression { // Input Processing err := vv.Check() @@ -616,32 +486,17 @@ func (vv VariableVector) SubstituteAccordingTo(subMap map[Variable]Expression) E } -/* -Power -Description: - - Raises the variable vector to the power of the input integer -*/ +// Power Raises the variable vector to the power of the input integer func (vv VariableVector) Power(exponent int) Expression { return VectorPowerTemplate(vv, exponent) } -/* -AsSimplifiedExpression -Description: - - Simplifies the expression and returns the simplified version. -*/ +// AsSimplifiedExpression Simplifies the expression and returns the simplified version. func (vv VariableVector) AsSimplifiedExpression() Expression { return vv } -/* -ToScalarExpressions -Description: - - Converts the VariableVector into a slice of ScalarExpression type objects. -*/ +// ToScalarExpressions Converts the VariableVector into a slice of ScalarExpression type objects. func (vv VariableVector) ToScalarExpressions() []ScalarExpression { var out []ScalarExpression for _, v := range vv { diff --git a/symbolic/vector_constraint.go b/symbolic/vector_constraint.go index 57911ef..0ae693d 100644 --- a/symbolic/vector_constraint.go +++ b/symbolic/vector_constraint.go @@ -7,25 +7,15 @@ import ( "gonum.org/v1/gonum/mat" ) -/* -vector_constraint.go -Description: - -*/ - +// VectorConstraint defines a constraint on two vector expressions. type VectorConstraint struct { LeftHandSide VectorExpression RightHandSide VectorExpression Sense ConstrSense } -/* -Dims -Description: - - The dimension of the vector constraint (ideally this should be the same as the dimensions - of the left and right hand sides). -*/ +// Dims The dimension of the vector constraint (ideally this should be the same as the dimensions +// of the left and right hand sides). func (vc VectorConstraint) Dims() []int { err := vc.Check() if err != nil { @@ -37,12 +27,7 @@ func (vc VectorConstraint) Dims() []int { } -/* -AtVec -Description: - - Retrieves the constraint formed by one element of the "vector" constraint. -*/ +// AtVec Retrieves the constraint formed by one element of the "vector" constraint. func (vc VectorConstraint) AtVec(i int) ScalarConstraint { // Input Processing err := vc.Check() @@ -63,12 +48,7 @@ func (vc VectorConstraint) AtVec(i int) ScalarConstraint { return ScalarConstraint{lhsAtI, rhsAtI, vc.Sense} } -/* -Check -Description: - - Checks that the VectorConstraint is valid. -*/ +// Check Checks that the VectorConstraint is valid. func (vc VectorConstraint) Check() error { // Constants @@ -100,43 +80,30 @@ func (vc VectorConstraint) Check() error { return nil } +// Left returns the left-hand side expression of the vector constraint. func (vc VectorConstraint) Left() Expression { return vc.LeftHandSide } +// Right returns the right-hand side expression of the vector constraint. func (vc VectorConstraint) Right() Expression { return vc.RightHandSide } -/* -ConstrSense -Description: - - Returns the sense of the constraint. -*/ +// ConstrSense Returns the sense of the constraint. func (vc VectorConstraint) ConstrSense() ConstrSense { return vc.Sense } -/* -IsLinear -Description: - - Describes whether a given vector constraint is - linear or not. -*/ +// IsLinear Describes whether a given vector constraint is +// linear or not. func (vc VectorConstraint) IsLinear() bool { return IsLinear(vc.RightHandSide) && IsLinear(vc.LeftHandSide) } -/* -LinearInequalityConstraintRepresentation -Description: - - Returns the linear constraint representation of the scalar constraint. - Returns a tuple of the form (A, b) where A is a vector and b is a constant such that: - A.Dot(x) <= b -*/ +// LinearInequalityConstraintRepresentation Returns the linear constraint representation of the scalar constraint. +// Returns a tuple of the form (A, b) where A is a vector and b is a constant such that: +// A.Dot(x) <= b func (vc VectorConstraint) LinearInequalityConstraintRepresentation(wrt ...[]Variable) (A mat.Dense, b mat.VecDense) { // Check that the constraint is well formed. err := vc.Check() @@ -199,14 +166,9 @@ func (vc VectorConstraint) LinearInequalityConstraintRepresentation(wrt ...[]Var return A, b } -/* -LinearEqualityConstraintRepresentation -Description: - - Returns the representation of the constraint as a linear equality constraint. - Returns a tuple of the form (C, d) where C is a matrix and d is a vector such that: - C*x = d -*/ +// LinearEqualityConstraintRepresentation Returns the representation of the constraint as a linear equality constraint. +// Returns a tuple of the form (C, d) where C is a matrix and d is a vector such that: +// C*x = d func (vc VectorConstraint) LinearEqualityConstraintRepresentation(wrt ...[]Variable) (C mat.Dense, d mat.VecDense) { // Check that the constraint is well formed. err := vc.Check() @@ -260,12 +222,7 @@ func (vc VectorConstraint) LinearEqualityConstraintRepresentation(wrt ...[]Varia return C, d } -/* -Substitute -Description: - - Substitutes the variable vIn with the scalar expression seIn in the vector constraint. -*/ +// Substitute Substitutes the variable vIn with the scalar expression seIn in the vector constraint. func (vc VectorConstraint) Substitute(vIn Variable, seIn ScalarExpression) Constraint { // Check that the constraint is well formed. err := vc.Check() @@ -281,12 +238,7 @@ func (vc VectorConstraint) Substitute(vIn Variable, seIn ScalarExpression) Const return VectorConstraint{newLHS, newRHS, vc.Sense} } -/* -SubstituteAccordingTo -Description: - - Substitutes the variables in the map with the corresponding expressions -*/ +// SubstituteAccordingTo Substitutes the variables in the map with the corresponding expressions func (vc VectorConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) Constraint { // Check that the constraint is well formed. err := vc.Check() @@ -302,12 +254,7 @@ func (vc VectorConstraint) SubstituteAccordingTo(subMap map[Variable]Expression) return VectorConstraint{newLHS, newRHS, vc.Sense} } -/* -Len -Description: - - Returns the length of the vector constraint. -*/ +// Len Returns the length of the vector constraint. func (vc VectorConstraint) Len() int { // Check that the constraint is well formed. err := vc.Check() @@ -319,12 +266,7 @@ func (vc VectorConstraint) Len() int { return vc.LeftHandSide.Len() } -/* -AsSimplifiedConstraint -Description: - - Simplifies the constraint by moving all variables to the left hand side and the constants to the right. -*/ +// AsSimplifiedConstraint Simplifies the constraint by moving all variables to the left hand side and the constants to the right. func (vc VectorConstraint) AsSimplifiedConstraint() Constraint { // Input Checking err := vc.Check() @@ -351,22 +293,12 @@ func (vc VectorConstraint) AsSimplifiedConstraint() Constraint { } } -/* -Variables -Description: - - Returns a slice of all the variables in the constraint. -*/ +// Variables Returns a slice of all the variables in the constraint. func (vc VectorConstraint) Variables() []Variable { return VariablesInThisConstraint(vc) } -/* -ImpliesThisIsAlsoSatisfied -Description: - - Returns true if this constraint implies that the other constraint is also satisfied. -*/ +// ImpliesThisIsAlsoSatisfied Returns true if this constraint implies that the other constraint is also satisfied. func (vc VectorConstraint) ImpliesThisIsAlsoSatisfied(other Constraint) bool { // Input Processing err := vc.Check() diff --git a/symbolic/vector_expression.go b/symbolic/vector_expression.go index 3c42ab2..8a72998 100644 --- a/symbolic/vector_expression.go +++ b/symbolic/vector_expression.go @@ -13,16 +13,11 @@ import ( "gonum.org/v1/gonum/mat" ) -/* -VectorExpression -Description: - - This interface represents any expression written in terms of a - vector of represents a linear general expression of the form - c0 * x0 + c1 * x1 + ... + cn * xn + k where ci are coefficients and xi are - variables and k is a constant. This is a base interface that is implemented - by single variables, constants, and general linear expressions. -*/ +// VectorExpression This interface represents any expression written in terms of a +// vector of represents a linear general expression of the form +// c0 * x0 + c1 * x1 + ... + cn * xn + k where ci are coefficients and xi are +// variables and k is a constant. This is a base interface that is implemented +// by single variables, constants, and general linear expressions. type VectorExpression interface { // Check returns an error if the expression is not valid Check() error @@ -103,12 +98,7 @@ type VectorExpression interface { ToScalarExpressions() []ScalarExpression } -/* -IsVectorExpression -Description: - - Determines whether or not an input object is a valid "VectorExpression" according to MatProInterface. -*/ +// IsVectorExpression Determines whether or not an input object is a valid "VectorExpression" according to MatProInterface. func IsVectorExpression(e interface{}) bool { // Check each type switch e.(type) { @@ -130,12 +120,7 @@ func IsVectorExpression(e interface{}) bool { } } -/* -ToVectorExpression -Description: - - Converts the input expression to a valid type that implements "VectorExpression". -*/ +// ToVectorExpression Converts the input expression to a valid type that implements "VectorExpression". func ToVectorExpression(e interface{}) (VectorExpression, error) { // Input Processing if !IsVectorExpression(e) { @@ -167,12 +152,7 @@ func ToVectorExpression(e interface{}) (VectorExpression, error) { } } -/* -ConcretizeVectorExpression -Description: - - Converts the input expression to a valid type that implements "VectorExpression". -*/ +// ConcretizeVectorExpression Converts the input expression to a valid type that implements "VectorExpression". func ConcretizeVectorExpression(sliceIn []ScalarExpression) VectorExpression { // Input Processing if len(sliceIn) == 0 { @@ -318,12 +298,7 @@ func ConcretizeVectorExpression(sliceIn []ScalarExpression) VectorExpression { } } -/* -VectorSubstituteTemplate -Description: - - Defines the template for the vector substitution operation. -*/ +// VectorSubstituteTemplate Defines the template for the vector substitution operation. func VectorSubstituteTemplate(ve VectorExpression, vIn Variable, se ScalarExpression) VectorExpression { // Input Processing err := ve.Check() @@ -352,12 +327,7 @@ func VectorSubstituteTemplate(ve VectorExpression, vIn Variable, se ScalarExpres return ConcretizeVectorExpression(result) } -/* -VectorPowerTemplate -Description: - - Defines the template for the vector power operation. -*/ +// VectorPowerTemplate Defines the template for the vector power operation. func VectorPowerTemplate(base VectorExpression, exponent int) Expression { // Setup @@ -390,6 +360,8 @@ func VectorPowerTemplate(base VectorExpression, exponent int) Expression { return result } +// VectorMultiplyTemplate multiplies a VectorExpression by a scalar Expression +// element-wise and returns the result. func VectorMultiplyTemplate(ve VectorExpression, right Expression) Expression { // Setup veAsSlice := ve.ToScalarExpressions() @@ -413,6 +385,8 @@ func VectorMultiplyTemplate(ve VectorExpression, right Expression) Expression { return ConcretizeExpression(prod) } +// VectorPlusTemplate adds a scalar Expression to each element of a VectorExpression +// and returns the result. func VectorPlusTemplate(ve VectorExpression, right Expression) Expression { // Setup veAsSlice := ve.ToScalarExpressions()