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

[Copilot]

The optim package needs to be formally deprecated in favor of github.com/MatProGo-dev/SymbolicMath.go, with all exported identifiers documented per Go doc conventions.

Changes

• New optim/doc.go: Package-level deprecation notice surfaced by go doc and IDEs
• All exported items: Every exported function, method, type, and constant across all 22 files now has a docstring starting with the identifier name and a Deprecated: notice, e.g.:

// INFINITY represents a large constant value used for unbounded constraints.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
const INFINITY = 1e100

// Model represents the overall constrained linear optimization model to be
// solved. It contains all variables, constraints, objective, and parameters.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
type Model struct { ... }

• Fixed duplicate import blocks in vector_constant.go and vector_constant_transpose.go (both had two separate import declarations; consolidated into one)
• No implementation logic changed

Original prompt

Objective

Update the comment structure in the entire optim package to:

1. Ensure all exported functions, types, methods, and constants have proper docstrings following standard Go doc principles
2. Mark all exported items as deprecated with clear migration guidance to the SymbolicMath.go module

Requirements

1. Go Doc Principles

All docstrings must follow these Go conventions:

• Start with the name of the item being documented
• Be complete sentences
• Use proper punctuation
• For functions: describe what the function does, its parameters, and return values
• For types: describe what the type represents

2. Deprecation Format

Every exported function, method, type, constant, and variable must include a deprecation notice in this format:

// FunctionName does something useful.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
func FunctionName() {}

3. Package-Level Documentation

Create a new file optim/doc.go with package-level deprecation notice:

// 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

4. Files to Update

Update ALL files in the optim package, including but not limited to:

• constant.go - K type and all methods
• errors.go - DimensionError, UnexpectedInputError types and methods
• expression.go - Expression interface and all functions
• model.go - Model type and all methods
• objective.go - Objective type and all functions
• operators.go - All operator functions (Eq, LessEq, GreaterEq, Comparison, Multiply)
• util.go - All utility functions (SumVars, SumRow, SumCol, FindInSlice) and INFINITY constant
• var_vector.go - VarVector type and all methods
• var_vector_transpose.go - VarVectorTranspose type and all methods
• vars.go - Variable type and all methods
• Any other files in the optim package

5. Specific Examples

Constants

// INFINITY represents a large constant value used for unbounded constraints.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
const INFINITY = 1e100

Functions

// SumVars returns the sum of the given variables by creating a new empty
// expression and adding the given variables to it.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
func SumVars(vs ...Variable) ScalarExpression {

Types

// Model represents the overall constrained linear optimization model to be
// solved. It contains all variables associated with the optimization
// problem, constraints, objective, and parameters. New variables can only be
// created using an instantiated Model.
//
// Deprecated: This package is deprecated. Please use github.com/MatProGo-dev/SymbolicMath.go instead.
type Model struct {

Methods

// 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 {

6. What NOT to Change

• Do NOT modify any implementation logic
• Do NOT change function signatures or behavior
• ONLY update comments/documentation
• Do NOT modify test files

7. Quality Standards

• Every exported item (starts with capital letter) MUST have a docstring
• All docstrings MUST start with the item name
• All items MUST include the deprecation notice
• Comments should be clear, concise, and grammatically correct
• Maintain consistent formatting throughout

8. Verification

After changes:

• All exported functions, types, methods, and constants should have proper documentation
• Running go doc on any exported item should show the deprecation notice
• The package should still compile without errors
• No functionality should be changed

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.77%. Comparing base (0214315) to head (c9a63e6).
⚠️ Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #35      +/-   ##
==========================================
- Coverage   86.76%   85.77%   -0.99%     
==========================================
  Files          27       35       +8     
  Lines        3687     3185     -502     
==========================================
- Hits         3199     2732     -467     
+ Misses        440      396      -44     
- Partials       48       57       +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.