File Formats¶

OptiScope supports multiple file formats for reading and writing optimization results. The I/O system is designed to be extensible, allowing you to add support for custom formats.

Supported Formats¶

JSON (`.json`)¶

The JSON format is the recommended format for OptiScope. It preserves all data, including:

Problem metadata
Variable metadata (bounds, units, etc.)
Result sets (Pareto front, user selections)
Full precision of numerical data

Use this format when you need to save your work and resume analysis later without losing any information.

CSV (`.csv`)¶

The CSV format is useful for interoperability with other tools (e.g., Excel, other plotting libraries).

Pros: Human-readable, widely supported.
Cons: Does not store rich metadata or result sets natively. OptiScope may infer some metadata, but it's not guaranteed to be perfect.

MIDACO (`.txt`)¶

OptiScope includes a handler for reading solution files from the MIDACO solver.

Loading and Saving Data¶

The easiest way to load and save data is using the top-level functions load_results and save_results. OptiScope automatically detects the file format based on the file extension.

from optiscope.io import load_results, save_results

# Load data
result = load_results("results.json")

# Save data to a different format
save_results(result, "export.csv")

Advanced Usage: Format Registry¶

OptiScope uses a FormatRegistry to manage handlers. You can interact with it directly if you need more control or want to register a custom handler.

from optiscope.io import get_global_registry

registry = get_global_registry()

# List available formats
formats = registry.list_formats()
print(formats)

# Explicitly use a specific handler
handler = registry.get_handler_for_file("results.json")
result = handler.read("results.json")

Adding Custom Formats¶

You can add support for a new file format by creating a class that inherits from BaseFormatHandler and registering it.

Create a Handler Class: Implement read, write, and can_handle methods.
Register the Handler: Use registry.register(MyHandler).

from optiscope.io.base import BaseFormatHandler
from optiscope.io import get_global_registry

class MyCustomHandler(BaseFormatHandler):
    format_name = "MyFormat"
    file_extensions = [".myfmt"]

    def read(self, filepath, **kwargs):
        # Implement reading logic
        pass

    def write(self, result, filepath, **kwargs):
        # Implement writing logic
        pass

# Register the new handler
get_global_registry().register(MyCustomHandler)