Skip to content

Commit b1b52f2

Browse files
CopilotkwesiRutledge
Copilot
and
kwesiRutledge
authored
Deprecate optim package: add Go-standard docstrings and deprecation notices (#35)
* Initial plan * Add deprecation notices and proper docstrings to all exported items in the optim package Co-authored-by: kwesiRutledge <9002730+kwesiRutledge@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: kwesiRutledge <9002730+kwesiRutledge@users.noreply.github.com>
1 parent 29e2a12 commit b1b52f2

23 files changed

Lines changed: 910 additions & 1279 deletions

‎optim/constant.go‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,45 +8,63 @@ import (
88

99
const (
1010
// Zero is a constant expression representing the value 0.
11+
//
12+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1113
Zero = K(0)
1214
// One is a constant expression representing the value 1.
15+
//
16+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1317
One = K(1)
1418
)
1519

1620
// K is a constant expression type for an MIP (Mixed Integer Program).
21+
//
22+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1723
type K float64
1824

1925
// Variables returns all variables included in the expression.
2026
// For constant K, there are no variables, so it returns an empty slice.
27+
//
28+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
2129
func (c K) Variables() []Variable {
2230
return []Variable{}
2331
}
2432

2533
// NumVars returns the number of variables in the expression.
2634
// For constant K, this is always 0.
35+
//
36+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
2737
func (c K) NumVars() int {
2838
return 0
2939
}
3040

3141
// IDs returns a slice of the variable IDs in the expression.
3242
// For constant K, this is always nil.
43+
//
44+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
3345
func (c K) IDs() []uint64 {
3446
return nil
3547
}
3648

3749
// Coeffs returns a slice of the coefficients in the expression.
3850
// For constant K, this is always nil.
51+
//
52+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
3953
func (c K) Coeffs() []float64 {
4054
return nil
4155
}
4256

4357
// Constant returns the constant additive value in the expression.
4458
// For constant K, this is just the constant's value.
59+
//
60+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
4561
func (c K) Constant() float64 {
4662
return float64(c)
4763
}
4864

4965
// Plus adds the current expression to another and returns the resulting expression.
66+
//
67+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
5068
func (c K) Plus(rightIn interface{}, errors ...error) (Expression, error) {
5169
// Input Processing
5270
err := CheckErrors(errors)
@@ -78,21 +96,29 @@ func (c K) Plus(rightIn interface{}, errors ...error) (Expression, error) {
7896
}
7997

8098
// LessEq returns a less than or equal to (<=) constraint between the current expression and another.
99+
//
100+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
81101
func (c K) LessEq(rightIn interface{}, errors ...error) (Constraint, error) {
82102
return c.Comparison(rightIn, SenseLessThanEqual, errors...)
83103
}
84104

85105
// GreaterEq returns a greater than or equal to (>=) constraint between the current expression and another.
106+
//
107+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
86108
func (c K) GreaterEq(rightIn interface{}, errors ...error) (Constraint, error) {
87109
return c.Comparison(rightIn, SenseGreaterThanEqual, errors...)
88110
}
89111

90112
// Eq returns an equality (==) constraint between the current expression and another.
113+
//
114+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
91115
func (c K) Eq(rightIn interface{}, errors ...error) (Constraint, error) {
92116
return c.Comparison(rightIn, SenseEqual, errors...)
93117
}
94118

95119
// Comparison compares the receiver with expression rhs in the sense provided by sense.
120+
//
121+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
96122
func (c K) Comparison(rhsIn interface{}, sense ConstrSense, errors ...error) (Constraint, error) {
97123
// InputProcessing
98124
err := CheckErrors(errors)
@@ -112,6 +138,8 @@ func (c K) Comparison(rhsIn interface{}, sense ConstrSense, errors ...error) (Co
112138
}
113139

114140
// Multiply multiplies the input constant by another expression.
141+
//
142+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
115143
func (c K) Multiply(term1 interface{}, errors ...error) (Expression, error) {
116144
// Constants
117145

@@ -217,19 +245,30 @@ func (c K) Multiply(term1 interface{}, errors ...error) (Expression, error) {
217245
}
218246
}
219247

248+
// Dims returns the dimensions of the constant K expression, which is always [1, 1] for a scalar.
249+
//
250+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
220251
func (c K) Dims() []int {
221252
return []int{1, 1} // Signifies scalar
222253
}
223254

255+
// Check verifies that the constant K expression is valid. For K, this always returns nil.
256+
//
257+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
224258
func (c K) Check() error {
225259
return nil
226260
}
227261

262+
// Transpose returns the transpose of the constant K expression, which is the constant itself.
263+
//
264+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
228265
func (c K) Transpose() Expression {
229266
return c
230267
}
231268

232269
// ToSymbolic converts the constant to a symbolic expression (i.e., one that uses the symbolic math toolbox).
270+
//
271+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
233272
func (c K) ToSymbolic() (symbolic.Expression, error) {
234273
return symbolic.K(c), nil
235274
}

‎optim/constr_sense.go‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,32 @@ package optim
33
import "github.com/MatProGo-dev/SymbolicMath.go/symbolic"
44

55
// ConstrSense represents if the constraint x <= y, x >= y, or x == y. For easy
6-
// integration with Gurobi, the senses have been encoding using a byte in
6+
// integration with Gurobi, the senses have been encoded using a byte in
77
// the same way Gurobi encodes the constraint senses.
8+
//
9+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
810
type ConstrSense byte
911

1012
// Different constraint senses conforming to Gurobi's encoding.
1113
const (
12-
SenseEqual ConstrSense = '='
13-
SenseLessThanEqual = '<'
14-
SenseGreaterThanEqual = '>'
14+
// SenseEqual represents the equality constraint sense (==).
15+
//
16+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
17+
SenseEqual ConstrSense = '='
18+
// SenseLessThanEqual represents the less-than-or-equal constraint sense (<=).
19+
//
20+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
21+
SenseLessThanEqual = '<'
22+
// SenseGreaterThanEqual represents the greater-than-or-equal constraint sense (>=).
23+
//
24+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
25+
SenseGreaterThanEqual = '>'
1526
)
1627

17-
/*
18-
ToSymbolic
19-
Description:
20-
21-
Converts a constraint sense to a the appropriate representation
22-
in the symbolic math toolbox.
23-
*/
28+
// ToSymbolic converts a constraint sense to the appropriate representation
29+
// in the symbolic math toolbox.
30+
//
31+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
2432
func (cs ConstrSense) ToSymbolic() symbolic.ConstrSense {
2533
switch cs {
2634
case SenseEqual:
@@ -33,12 +41,9 @@ func (cs ConstrSense) ToSymbolic() symbolic.ConstrSense {
3341
return '1'
3442
}
3543

36-
/*
37-
String
38-
Description:
39-
40-
Returns the string representation of the constraint sense.
41-
*/
44+
// String returns the string representation of the constraint sense.
45+
//
46+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
4247
func (cs ConstrSense) String() string {
4348
switch cs {
4449
case SenseEqual:

‎optim/constraint.go‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,20 @@
11
package optim
22

3-
/*
4-
constraint.go
5-
Description:
6-
Defines an interface that we are meant to use with the ScalarContraint and VectorConstraint
7-
objects.
8-
*/
9-
3+
// Constraint is an interface for use with the ScalarConstraint and
4+
// VectorConstraint objects.
5+
//
6+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
107
type Constraint interface {
118
Left() Expression
129
Right() Expression
1310
ConstrSense() ConstrSense
1411
Check() error
1512
}
1613

14+
// IsConstraint returns true if the input is a valid Constraint type
15+
// (ScalarConstraint or VectorConstraint).
16+
//
17+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1718
func IsConstraint(c interface{}) bool {
1819
switch c.(type) {
1920
case ScalarConstraint:

‎optim/doc.go‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// Package optim provides interfaces and types for modeling Mathematical Programs
2+
// (e.g., Convex Optimization problems) in Go.
3+
//
4+
// Deprecated: This package is deprecated and will not receive further updates.
5+
// Users should migrate to github.com/MatProGo-dev/SymbolicMath.go which provides
6+
// improved functionality and ongoing support.
7+
package optim

‎optim/errors.go‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,30 @@ dimension.go
1010

1111
/* Type Definitions */
1212

13+
// DimensionError represents an error that occurs when two expressions have
14+
// incompatible dimensions for a given operation.
15+
//
16+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1317
type DimensionError struct {
1418
Arg1 Expression
1519
Arg2 Expression
1620
Operation string // Either multiply or Plus
1721
}
1822

23+
// UnexpectedInputError represents an error that occurs when an unexpected
24+
// input type is provided to an operation.
25+
//
26+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
1927
type UnexpectedInputError struct {
2028
InputInQuestion interface{}
2129
Operation string
2230
}
2331

2432
/* Methods */
2533

34+
// Error returns a string representation of the DimensionError.
35+
//
36+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
2637
func (de DimensionError) Error() string {
2738
dimStrings := de.ArgDimsAsStrings()
2839
return fmt.Sprintf(
@@ -33,6 +44,9 @@ func (de DimensionError) Error() string {
3344
)
3445
}
3546

47+
// ArgDimsAsStrings returns the dimensions of both arguments as a slice of strings.
48+
//
49+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
3650
func (de DimensionError) ArgDimsAsStrings() []string {
3751
// Create string for arg 1
3852
arg1DimsAsString := "("
@@ -58,6 +72,9 @@ func (de DimensionError) ArgDimsAsStrings() []string {
5872

5973
}
6074

75+
// Error returns a string representation of the UnexpectedInputError.
76+
//
77+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
6178
func (uie UnexpectedInputError) Error() string {
6279
return fmt.Sprintf(
6380
"Unexpected input to \"%v\" operation: %T",

‎optim/expression.go‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,11 @@ import (
44
"fmt"
55
"github.com/MatProGo-dev/SymbolicMath.go/symbolic"
66
)
7-
8-
/*
9-
matrix_expression.go
10-
Description:
11-
This file holds all of the functions and methods related to the Expression
12-
interface.
13-
*/
14-
15-
/*
16-
Expression
17-
Description:
18-
19-
This interface should be implemented by and ScalarExpression and VectorExpression
20-
*/
7+
// Expression is an interface that should be implemented by any ScalarExpression
8+
// and VectorExpression. It provides methods for arithmetic operations and
9+
// constraint creation.
10+
//
11+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
2112
type Expression interface {
2213
// NumVars returns the number of variables in the expression
2314
NumVars() int
@@ -59,16 +50,17 @@ type Expression interface {
5950
ToSymbolic() (symbolic.Expression, error)
6051
}
6152

62-
/*
63-
IsExpression
64-
Description:
65-
66-
Tests whether or not the input variable is one of the expression types.
67-
*/
53+
// IsExpression tests whether or not the input variable is one of the expression types.
54+
//
55+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
6856
func IsExpression(e interface{}) bool {
6957
return IsScalarExpression(e) || IsVectorExpression(e)
7058
}
7159

60+
// ToExpression converts the input to an Expression, returning an error if the
61+
// input is not a recognized scalar or vector expression type.
62+
//
63+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
7264
func ToExpression(e interface{}) (Expression, error) {
7365
switch {
7466
case IsScalarExpression(e):
@@ -80,6 +72,11 @@ func ToExpression(e interface{}) (Expression, error) {
8072
}
8173
}
8274

75+
// CheckDimensionsInMultiplication checks that the dimensions of the two
76+
// expressions are compatible for multiplication. It returns an error if the
77+
// number of columns in left does not match the number of rows in right.
78+
//
79+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
8380
func CheckDimensionsInMultiplication(left, right Expression) error {
8481
// Check that the # of columns in left
8582
// matches the # of rows in right
@@ -94,6 +91,11 @@ func CheckDimensionsInMultiplication(left, right Expression) error {
9491
return nil
9592
}
9693

94+
// CheckDimensionsInAddition checks that the dimensions of the two expressions
95+
// are compatible for addition. It returns an error if the dimensions do not match,
96+
// unless one of the expressions is a scalar expression.
97+
//
98+
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
9799
func CheckDimensionsInAddition(left, right Expression) error {
98100
// Check that the size of columns in left and right agree
99101
dimsAreMatched := (left.Dims()[0] == right.Dims()[0]) && (left.Dims()[1] == right.Dims()[1])

0 commit comments

Comments
 (0)