Deprecate optim package: add Go-standard docstrings and deprecation notices

optim/constant.go

@@ -8,45 +8,63 @@ import (
 
 const (
 	// Zero is a constant expression representing the value 0.
+	//
+	// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 	Zero = K(0)
 	// One is a constant expression representing the value 1.
+	//
+	// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 	One = K(1)
 )
 
 // K is a constant expression type for an MIP (Mixed Integer Program).
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type K float64
 
 // Variables returns all variables included in the expression.
 // For constant K, there are no variables, so it returns an empty slice.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Variables() []Variable {
 	return []Variable{}
 }
 
 // NumVars returns the number of variables in the expression.
 // For constant K, this is always 0.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) NumVars() int {
 	return 0
 }
 
 // IDs returns a slice of the variable IDs in the expression.
 // For constant K, this is always nil.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) IDs() []uint64 {
 	return nil
 }
 
 // Coeffs returns a slice of the coefficients in the expression.
 // For constant K, this is always nil.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Coeffs() []float64 {
 	return nil
 }
 
 // Constant returns the constant additive value in the expression.
 // For constant K, this is just the constant's value.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Constant() float64 {
 	return float64(c)
 }
 
 // Plus adds the current expression to another and returns the resulting expression.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Plus(rightIn interface{}, errors ...error) (Expression, error) {
 	// Input Processing
 	err := CheckErrors(errors)
@@ -78,21 +96,29 @@ func (c K) Plus(rightIn interface{}, errors ...error) (Expression, error) {
 }
 
 // LessEq returns a less than or equal to (<=) constraint between the current expression and another.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) LessEq(rightIn interface{}, errors ...error) (Constraint, error) {
 	return c.Comparison(rightIn, SenseLessThanEqual, errors...)
 }
 
 // GreaterEq returns a greater than or equal to (>=) constraint between the current expression and another.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) GreaterEq(rightIn interface{}, errors ...error) (Constraint, error) {
 	return c.Comparison(rightIn, SenseGreaterThanEqual, errors...)
 }
 
 // Eq returns an equality (==) constraint between the current expression and another.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Eq(rightIn interface{}, errors ...error) (Constraint, error) {
 	return c.Comparison(rightIn, SenseEqual, errors...)
 }
 
 // Comparison compares the receiver with expression rhs in the sense provided by sense.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Comparison(rhsIn interface{}, sense ConstrSense, errors ...error) (Constraint, error) {
 	// InputProcessing
 	err := CheckErrors(errors)
@@ -112,6 +138,8 @@ func (c K) Comparison(rhsIn interface{}, sense ConstrSense, errors ...error) (Co
 }
 
 // Multiply multiplies the input constant by another expression.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Multiply(term1 interface{}, errors ...error) (Expression, error) {
 	// Constants
 
@@ -217,19 +245,30 @@ func (c K) Multiply(term1 interface{}, errors ...error) (Expression, error) {
 	}
 }
 
+// Dims returns the dimensions of the constant K expression, which is always [1, 1] for a scalar.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Dims() []int {
 	return []int{1, 1} // Signifies scalar
 }
 
+// Check verifies that the constant K expression is valid. For K, this always returns nil.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Check() error {
 	return nil
 }
 
+// Transpose returns the transpose of the constant K expression, which is the constant itself.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) Transpose() Expression {
 	return c
 }
 
 // ToSymbolic converts the constant to a symbolic expression (i.e., one that uses the symbolic math toolbox).
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (c K) ToSymbolic() (symbolic.Expression, error) {
 	return symbolic.K(c), nil
 }

optim/constr_sense.go

@@ -3,24 +3,32 @@ package optim
 import "github.com/MatProGo-dev/SymbolicMath.go/symbolic"
 
 // ConstrSense represents if the constraint x <= y, x >= y, or x == y. For easy
-// integration with Gurobi, the senses have been encoding using a byte in
+// integration with Gurobi, the senses have been encoded using a byte in
 // the same way Gurobi encodes the constraint senses.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type ConstrSense byte
 
 // Different constraint senses conforming to Gurobi's encoding.
 const (
-	SenseEqual            ConstrSense = '='
-	SenseLessThanEqual                = '<'
-	SenseGreaterThanEqual             = '>'
+	// SenseEqual represents the equality constraint sense (==).
+	//
+	// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
+	SenseEqual ConstrSense = '='
+	// SenseLessThanEqual represents the less-than-or-equal constraint sense (<=).
+	//
+	// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
+	SenseLessThanEqual = '<'
+	// SenseGreaterThanEqual represents the greater-than-or-equal constraint sense (>=).
+	//
+	// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
+	SenseGreaterThanEqual = '>'
 )
 
-/*
-ToSymbolic
-Description:
-
-	Converts a constraint sense to a the appropriate representation
-	in the symbolic math toolbox.
-*/
+// ToSymbolic converts a constraint sense to the appropriate representation
+// in the symbolic math toolbox.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (cs ConstrSense) ToSymbolic() symbolic.ConstrSense {
 	switch cs {
 	case SenseEqual:
@@ -33,12 +41,9 @@ func (cs ConstrSense) ToSymbolic() symbolic.ConstrSense {
 	return '1'
 }
 
-/*
-String
-Description:
-
-	Returns the string representation of the constraint sense.
-*/
+// String returns the string representation of the constraint sense.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (cs ConstrSense) String() string {
 	switch cs {
 	case SenseEqual:

optim/constraint.go

@@ -1,19 +1,20 @@
 package optim
 
-/*
-constraint.go
-Description:
-	Defines an interface that we are meant to use with the ScalarContraint and VectorConstraint
-	objects.
-*/
-
+// Constraint is an interface for use with the ScalarConstraint and
+// VectorConstraint objects.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type Constraint interface {
 	Left() Expression
 	Right() Expression
 	ConstrSense() ConstrSense
 	Check() error
 }
 
+// IsConstraint returns true if the input is a valid Constraint type
+// (ScalarConstraint or VectorConstraint).
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func IsConstraint(c interface{}) bool {
 	switch c.(type) {
 	case ScalarConstraint:

optim/doc.go

@@ -0,0 +1,7 @@
+// Package optim provides interfaces and types for modeling Mathematical Programs
+// (e.g., Convex Optimization problems) in Go.
+//
+// Deprecated: This package is deprecated and will not receive further updates.
+// Users should migrate to github.com/MatProGo-dev/SymbolicMath.go which provides
+// improved functionality and ongoing support.
+package optim

optim/errors.go

@@ -10,19 +10,30 @@ dimension.go
 
 /* Type Definitions */
 
+// DimensionError represents an error that occurs when two expressions have
+// incompatible dimensions for a given operation.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type DimensionError struct {
 	Arg1      Expression
 	Arg2      Expression
 	Operation string // Either multiply or Plus
 }
 
+// UnexpectedInputError represents an error that occurs when an unexpected
+// input type is provided to an operation.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type UnexpectedInputError struct {
 	InputInQuestion interface{}
 	Operation       string
 }
 
 /* Methods */
 
+// Error returns a string representation of the DimensionError.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (de DimensionError) Error() string {
 	dimStrings := de.ArgDimsAsStrings()
 	return fmt.Sprintf(
@@ -33,6 +44,9 @@ func (de DimensionError) Error() string {
 	)
 }
 
+// ArgDimsAsStrings returns the dimensions of both arguments as a slice of strings.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (de DimensionError) ArgDimsAsStrings() []string {
 	// Create string for arg 1
 	arg1DimsAsString := "("
@@ -58,6 +72,9 @@ func (de DimensionError) ArgDimsAsStrings() []string {
 
 }
 
+// Error returns a string representation of the UnexpectedInputError.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func (uie UnexpectedInputError) Error() string {
 	return fmt.Sprintf(
 		"Unexpected input to \"%v\" operation: %T",

optim/expression.go

@@ -4,20 +4,11 @@ import (
 	"fmt"
 	"github.com/MatProGo-dev/SymbolicMath.go/symbolic"
 )
-
-/*
-matrix_expression.go
-Description:
-	This file holds all of the functions and methods related to the Expression
-	interface.
-*/
-
-/*
-Expression
-Description:
-
-	This interface should be implemented by and ScalarExpression and VectorExpression
-*/
+// Expression is an interface that should be implemented by any ScalarExpression
+// and VectorExpression. It provides methods for arithmetic operations and
+// constraint creation.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 type Expression interface {
 	// NumVars returns the number of variables in the expression
 	NumVars() int
@@ -59,16 +50,17 @@ type Expression interface {
 	ToSymbolic() (symbolic.Expression, error)
 }
 
-/*
-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.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func IsExpression(e interface{}) bool {
 	return IsScalarExpression(e) || IsVectorExpression(e)
 }
 
+// ToExpression converts the input to an Expression, returning an error if the
+// input is not a recognized scalar or vector expression type.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func ToExpression(e interface{}) (Expression, error) {
 	switch {
 	case IsScalarExpression(e):
@@ -80,6 +72,11 @@ func ToExpression(e interface{}) (Expression, error) {
 	}
 }
 
+// CheckDimensionsInMultiplication checks that the dimensions of the two
+// expressions are compatible for multiplication. It returns an error if the
+// number of columns in left does not match the number of rows in right.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func CheckDimensionsInMultiplication(left, right Expression) error {
 	// Check that the # of columns in left
 	// matches the # of rows in right
@@ -94,6 +91,11 @@ func CheckDimensionsInMultiplication(left, right Expression) error {
 	return nil
 }
 
+// CheckDimensionsInAddition checks that the dimensions of the two expressions
+// are compatible for addition. It returns an error if the dimensions do not match,
+// unless one of the expressions is a scalar expression.
+//
+// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
 func CheckDimensionsInAddition(left, right Expression) 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])