Skip to content

5-Minute Quickstart

Get up and running with OptiScope in just a few minutes!

Installation

pip install optiscope

That's it! OptiScope and its dependencies are now installed.

Your First Analysis

Let's analyze a multi-objective optimization result in four simple steps.

Step 1: Load Data

OptiScope automatically detects file formats:

from optiscope import load_results

# Load from CSV, JSON, or HDF5
result = load_results("optimization_results.csv")

# Check what we have
print(f"Loaded {result.n_points} solutions")
print(f"Objectives: {list(result.objectives.columns)}")
print(f"Design variables: {list(result.design_variables.columns)}")

Output: 

Loaded 500 solutions
Objectives: ['f1_cost', 'f2_weight', 'f3_efficiency']
Design variables: ['x1_width', 'x2_height', 'x3_depth']

Step 2: Visualize

Create an interactive Pareto front visualization:

from optiscope.plotting import plot_pareto_front_2d

fig = plot_pareto_front_2d(
    result,
    obj_x="f1_cost",
    obj_y="f2_weight",
    show_dominated=True,
    show_ideal_nadir=True
)

fig.show()  # Opens in browser
# Or save: fig.write_html("pareto_front.html")

Result:

An interactive plot will open in your browser showing the Pareto front with hover details.

Step 3: Analyze

Filter to representative Pareto points and find knee points:

from optiscope.analysis import smart_pareto_filter, detect_knee_points

# Get representative subset
pareto_indices = smart_pareto_filter(
    result.objectives[['f1_cost', 'f2_weight']],
    epsilon=0.15
)
result.create_set("pareto", pareto_indices, "smart_filter")

print(f"Reduced from {result.n_points} to {len(pareto_indices)} points")

# Find best compromise (knee point)
pareto_objectives = result.objectives[['f1_cost', 'f2_weight']].iloc[pareto_indices]
knee_indices = detect_knee_points(pareto_objectives, method='angle', n_knees=3)

# Map back to original indices
knee_original = pareto_indices[knee_indices]
result.create_set("knees", knee_original, "knee_detection")

print(f"\nKnee points (best compromises):")
for i, idx in enumerate(knee_original):
    print(f"  {i+1}. Solution {idx}:")
    print(f"     Cost: {result.objectives.loc[idx, 'f1_cost']:.2f}")
    print(f"     Weight: {result.objectives.loc[idx, 'f2_weight']:.2f}")

Output: 

Reduced from 500 to 47 points

Knee points (best compromises):
  1. Solution 234:
     Cost: 152.34
     Weight: 23.45
  2. Solution 156:
     Cost: 189.21
     Weight: 18.92
  3. Solution 78:
     Cost: 210.45
     Weight: 16.34

Step 4: Make Decisions

Rank solutions using TOPSIS (multi-criteria decision making):

from optiscope.analysis import topsis_from_result

# Rank with your preferences
topsis_result = topsis_from_result(
    result,
    weights={
        'f1_cost': 0.5,      # 50% weight on cost
        'f2_weight': 0.3,    # 30% weight on weight
        'f3_efficiency': 0.2 # 20% weight on efficiency
    },
    subset_name="pareto"     # Analyze only Pareto set
)

# Get top 5 solutions
top_5 = topsis_result['ranks'][:5]

print("Top 5 solutions based on your preferences:")
for i, idx in enumerate(top_5, 1):
    score = topsis_result['scores'][idx]
    print(f"{i}. Solution {idx} (score: {score:.4f})")
    print(f"   Cost: {result.objectives.loc[idx, 'f1_cost']:.2f}")
    print(f"   Weight: {result.objectives.loc[idx, 'f2_weight']:.2f}")
    print(f"   Efficiency: {result.objectives.loc[idx, 'f3_efficiency']:.2f}")

Complete Example

Here's the full workflow in one script:

quickstart_example.py
from optiscope import load_results
from optiscope.plotting import plot_pareto_front_2d
from optiscope.analysis import (
    smart_pareto_filter,
    detect_knee_points,
    topsis_from_result
)

# 1. Load data
result = load_results("optimization_results.csv")

# 2. Filter to representative points
pareto_indices = smart_pareto_filter(
    result.objectives[['f1_cost', 'f2_weight']],
    epsilon=0.15
)
result.create_set("pareto", pareto_indices, "smart_filter")

# 3. Find knee points
pareto_obj = result.objectives[['f1_cost', 'f2_weight']].iloc[pareto_indices]
knee_indices = detect_knee_points(pareto_obj, method='angle', n_knees=3)
result.create_set("knees", pareto_indices[knee_indices], "knee_detection")

# 4. Visualize everything
fig = plot_pareto_front_2d(
    result,
    obj_x="f1_cost",
    obj_y="f2_weight",
    pareto_set="pareto",
    additional_sets=["knees"],
    show_dominated=True,
    show_ideal_nadir=True
)
fig.write_html("analysis_results.html")

# 5. Rank with TOPSIS
topsis_result = topsis_from_result(
    result,
    weights={'f1_cost': 0.5, 'f2_weight': 0.3, 'f3_efficiency': 0.2},
    subset_name="pareto"
)

print(f"Best solution: {topsis_result['ranks'][0]}")

What's Next?

  • Core Concepts

    Understand the key concepts behind OptiScope.

    Learn More

  • Examples

    Browse interactive notebooks and scripts.

    Examples

  • API Reference

    Explore the complete API documentation.

    API Docs

Common Tasks

Load Different File Formats

# CSV with automatic column detection
result = load_results("data.csv")

# JSON with full metadata
result = load_results("data.json")

# Custom column prefixes for CSV
result = load_results(
    "data.csv",
    design_var_prefix="dv_",
    objective_prefix="obj_"
)

Create and Save Results

from optiscope import OptimizationResult, save_results
import pandas as pd

result = OptimizationResult(
    design_variables=pd.DataFrame(...),
    objectives=pd.DataFrame(...),
    ...
)

# Save with all metadata
save_results(result, "my_results.json")

Use Storage for Persistence

from optiscope.storage import FileSystemStorage

# Create storage backend
storage = FileSystemStorage(base_path="./results", format="json")

# Save
storage.save_result("run_001", result)

# Load later
result = storage.load_result("run_001")

Create More Visualizations

from optiscope.plotting import (
    plot_parallel_coordinates,
    plot_scatter_matrix,
    plot_pareto_front_3d
)

# Parallel coordinates with feasibility
fig1 = plot_parallel_coordinates(
    result,
    include_objectives=True,
    include_design_vars=True,
    highlight_feasible=True
)

# Scatter matrix for correlations
fig2 = plot_scatter_matrix(
    result,
    max_vars=6,
    show_correlations=True
)

# 3D Pareto front
fig3 = plot_pareto_front_3d(
    result,
    obj_x=0, obj_y=1, obj_z=2,
    pareto_set="pareto"
)

Tips

Auto-Detection

OptiScope automatically detects file formats and column types using naming conventions. Use x_* for design variables, f_* for objectives, g_* for inequality constraints.

Interactive Plots

All plots are interactive! Hover for details, zoom, pan, and save as images.

Result Sets

Create named subsets (like "pareto", "knees") and use them across all visualizations and analyses.

Storage

Use storage backends for large datasets or when you need persistence between sessions.

Need Help?