Installation

This guide will help you install OptiX and its dependencies on your system.

System Requirements

Python Requirements

OptiX requires Python 3.12 or higher. Check your Python version:

python --version

If you need to install or upgrade Python, visit the official Python website.

Poetry Installation

OptiX uses Poetry for dependency management. Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

pip install poetry

Verify Poetry installation:

poetry --version

Hardware Recommendations

Component	Minimum	Recommended
CPU	Dual-core processor	Quad-core or higher
RAM	4GB	8GB or more
Storage	1GB free space	5GB+ for development
Network	Internet connection for installation	Stable connection for updates

Installing OptiX

Clone the Repository

# Clone from GitHub
git clone https://github.com/yourusername/optix.git
cd OptiX

Install Dependencies

# Install all dependencies including development tools
poetry install

# Install only production dependencies
poetry install --no-dev

Activate Virtual Environment

# Activate the Poetry virtual environment
poetry shell

# Or run commands with Poetry
poetry run python your_script.py

Solver Installation

OptiX supports multiple optimization solvers. Install the ones you need:

OR-Tools (Recommended)

OR-Tools is automatically installed with OptiX dependencies.

# Verify OR-Tools installation
poetry run python -c "import ortools; print('OR-Tools version:', ortools.__version__)"

Note

OR-Tools is free and open-source, making it the recommended solver for getting started.

Gurobi (Commercial)

Download and Install Gurobi

Visit Gurobi Downloads
Create a free account
Download the appropriate version for your platform
Follow the installation instructions for your operating system

Get a License

Visit Gurobi Academic Licenses
Register with your academic email
Download the license file
Follow activation instructions

Set Environment Variables

Add to your .bashrc or .zshrc:

export GUROBI_HOME="/opt/gurobi1000/linux64"
export PATH="${PATH}:${GUROBI_HOME}/bin"
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${GUROBI_HOME}/lib"

Set environment variables in System Properties:

GUROBI_HOME=C:\gurobi1000\win64
PATH=%PATH%;%GUROBI_HOME%\bin
LD_LIBRARY_PATH=%LD_LIBRARY_PATH%;%GUROBI_HOME%\lib

Install Python Interface

# Install Gurobi Python package
poetry run pip install gurobipy

# Verify installation
poetry run python -c "import gurobipy; print('Gurobi installed successfully')"

Alternative Installation Methods

Using pip (Not Recommended)

If you prefer pip over Poetry:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies (if requirements.txt exists)
pip install -r requirements.txt

Development Installation

For contributing to OptiX development:

# Clone the repository
git clone https://github.com/yourusername/optix.git
cd OptiX

# Install with development dependencies
poetry install --with dev,test,docs

# Install pre-commit hooks
poetry run pre-commit install

# Run tests to verify installation
poetry run pytest

Verification

Test your installation with this simple script:

# test_installation.py
from problem import OXLPProblem, ObjectiveType
from constraints import RelationalOperators
from solvers import solve, get_available_solvers

def test_installation():
    print("=== OptiX Installation Test ===")

    # Check available solvers
    solvers = get_available_solvers()
    print(f"Available solvers: {solvers}")

    # Create a simple problem
    problem = OXLPProblem()
    problem.create_decision_variable("x", "Test variable", 0, 10)

    problem.create_constraint(
        variables=[problem.variables[0].id],
        weights=[1],
        operator=RelationalOperators.LESS_THAN_EQUAL,
        value=5
    )

    problem.create_objective_function(
        variables=[problem.variables[0].id],
        weights=[1],
        objective_type=ObjectiveType.MAXIMIZE
    )

    # Test solving
    for solver in solvers:
        try:
            status, solution = solve(problem, solver)
            print(f"✅ {solver}: {status}")
            if solution:
                print(f"   Objective value: {solution[0].objective_value}")
        except Exception as e:
            print(f"❌ {solver}: {e}")

    print("\n✅ Installation test completed!")

if __name__ == "__main__":
    test_installation()

Run the test:

poetry run python test_installation.py

Troubleshooting

Common Issues

Poetry not found

# Add Poetry to PATH (macOS/Linux)
export PATH="$HOME/.local/bin:$PATH"

# Restart your terminal and try again

OR-Tools import error

# Reinstall OR-Tools
poetry run pip uninstall ortools-python
poetry install --force

Gurobi license error

# Check license status
grbgetkey your-license-key

# Verify license file location
echo $GRB_LICENSE_FILE

Permission errors (Linux/macOS)

# Fix permissions for Poetry installation
sudo chown -R $(whoami) ~/.local/share/pypoetry

Getting Help

If you encounter issues:

Check the GitHub Issues page
Review the ../development/troubleshooting section
Join our community discussions
Contact the development team

Tip

Quick Start: Once installed, head to the Quick Start Guide guide to create your first optimization problem!

Note

Performance Note: For large-scale problems, consider installing Gurobi for better performance, especially for mixed-integer programming problems.