Beginner• 15 minutes

Getting Started with Sematryx

Solve your first optimization problem and learn the core concepts of Sematryx.

What You'll Learn

In this tutorial, you'll solve a simple optimization problem and understand the key concepts:

  • •Defining objective functions
  • •Setting search bounds
  • •Running optimization with Sematryx
  • •Understanding results and explanations
  • •Configuring Sematryx Intelligence

Prerequisites

Before You Start

  • ✓Python 3.8+ installed
  • ✓Basic Python programming knowledge
  • ✓Understanding of optimization concepts (minimization/maximization)

For API access, you'll need an API key from the API Keys page

Step 1: Install Sematryx

Install the Sematryx Python SDK:

Install Sematryx
pip install sematryx

Step 2: Your First Optimization

Let's solve a classic optimization problem—minimizing the sphere function. This is a 2D problem where we want to find the point closest to the origin:

Basic optimization example
from sematryx import optimize

# Define your objective function
def sphere(x):
    """Minimize the sum of squares (classic optimization test)"""
    return sum(xi**2 for xi in x)

# Run optimization
# API key can be provided or set via SEMATRYX_API_KEY env var
result = optimize(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],  # 2D problem
    max_evaluations=1000,
    api_key="sk-..."  # or set SEMATRYX_API_KEY environment variable
)

print(f"Best solution: {result.solution}")
print(f"Best value: {result.objective_value}")
print(f"Evaluations used: {result.evaluations_used}")

What's Happening?

  • Objective Function: sphere(x) calculates sum of squares—we want to minimize this
  • Bounds: Search space is [-5, 5] for each dimension
  • Max Evaluations: Sematryx will evaluate the function up to 1000 times
  • Result: Best solution found (should be near [0, 0]) and its objective value

Step 3: Understanding the Results

Sematryx returns an OptimizationResult object with optimization results and explanations:

Optimization result
result.solution        # {'x0': 0.001, 'x1': -0.002}
result.objective_value  # 0.000005
result.evaluations_used # 847
result.duration_seconds # 1.23
result.strategy_used    # "cma_es"
result.explanation      # "Converged to global minimum..."
result.success         # True

Result Fields

  • result.solution: Dictionary of optimal parameter values (e.g., {'x0': 0.001, 'x1': -0.002})
  • result.objective_value: Best objective value achieved
  • result.evaluations_used: Number of function evaluations used
  • result.strategy_used: Which optimization algorithm Sematryx selected
  • result.explanation: Why this strategy was chosen and how it performed
  • result.success: Whether optimization succeeded

Step 4: Configure the Optimization Engine

Sematryx's optimization engine has three pillars you can enable for enhanced optimization:

Engine configuration
from sematryx import optimize

# Configure the engine's three core pillars
result = optimize(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],
    
    # Interpretable: Get detailed explanations
    explanation_level=3,
    
    # Learning: Enable private learning store
    learning={
        "read_from_public": True,
        "write_to_private": True
    }
)

The Three Core Pillars

  • Agentic Intelligence: Multiple AI agents collaborate to select the best optimization strategy
  • Interpretable Intelligence: Get explanations of optimization decisions (levels 0-5 for detail)
  • Adaptive Intelligence: System learns from your optimizations to improve over time

Step 5: Real-World Example

Here's a more practical example—optimizing a portfolio allocation:

Portfolio optimization example
from sematryx import optimize
import numpy as np

# Real-world example: Portfolio optimization
def portfolio_risk(weights):
    """
    Minimize portfolio risk given expected returns
    weights: [w1, w2, w3] - allocation percentages
    """
    returns = np.array([0.12, 0.08, 0.15])  # Expected returns
    covariance = np.array([
        [0.04, 0.01, 0.02],
        [0.01, 0.03, 0.01],
        [0.02, 0.01, 0.05]
    ])
    
    # Portfolio variance (risk)
    portfolio_variance = np.dot(weights, np.dot(covariance, weights))
    
    # Penalty for not summing to 1
    constraint_penalty = 1000 * abs(sum(weights) - 1)
    
    return portfolio_variance + constraint_penalty

# Optimize
result = optimize(
    objective_function=portfolio_risk,
    bounds=[[0, 1], [0, 1], [0, 1]],
    max_evaluations=2000,
    explanation_level=2  # Get rationale
)

print(f"Optimal allocation: {result.solution}")
print(f"Risk value: {result.objective_value:.6f}")
print(f"Explanation: {result.explanation}")

This example shows how to optimize a real-world problem with constraints and get explanations you can present to stakeholders.

🎉 Congratulations!

You've solved your first optimization problem with Sematryx! You now understand how to define problems, run optimization, and interpret results.

What's Next?

→ Learn about complex problem setup and constraints→ Master Sematryx Intelligence configuration→ Explore the full API documentation