Skip to Content
SdkSDK API Reference

SDK API Reference

Complete reference for all OptixLog SDK functions, classes, and methods.

optixlog.run() - Context Manager (Recommended)

Initialize an OptixLog client using a context manager for automatic cleanup.

with optixlog.run(
    run_name: str,
    project: Optional[str] = None,
    config: Optional[Dict[str, Any]] = None,
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    create_project_if_not_exists: bool = True,
    task_id: Optional[str] = None
) as client:
    # Your code here
    client.log(step=0, loss=0.5)
# Automatic cleanup when done

Parameters

ParameterTypeDefaultDescription
run_namestrRequiredName for this run.
projectstr | NoneNoneProject name. Uses OPTIX_PROJECT env var or "dev" if not set.
configDict[str, Any] | NoneNoneConfiguration dictionary to store with the run.
api_keystr | NoneNoneAPI key. Automatically uses OPTIX_API_KEY env var if not provided. Only required if not set in environment.
api_urlstr | NoneNoneAPI endpoint URL. Uses OPTIX_API_URL env var or default URL.
create_project_if_not_existsboolTrueAutomatically create project if it doesn’t exist.
task_idstr | NoneNoneOptional task ID to link this run to.

Returns

OptixClient - A client instance ready for logging (use with with statement).

Example

import optixlog
 
# API key is automatically read from OPTIX_API_KEY environment variable
# No need to pass it explicitly if you've set the environment variable
with optixlog.run(
    "my_experiment",
    project="MyProject",
    config={"wavelength": 1.55, "resolution": 30}
) as client:
    for step in range(100):
        client.log(step=step, loss=calculate_loss())

optixlog.init()

Initialize an OptixLog client (traditional approach).

client = optixlog.init(
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    project: Optional[str] = None,
    run_name: Optional[str] = None,
    config: Optional[Dict[str, Any]] = None,
    create_project_if_not_exists: bool = False,
    task_id: Optional[str] = None
)

Parameters

Same as optixlog.run(), but run_name is optional here.

Returns

OptixClient - A client instance ready for logging.

Example

# API key is automatically read from OPTIX_API_KEY environment variable
client = optixlog.init(run_name="my_experiment")
client.log(step=0, loss=0.5)

OptixClient Class

Main client class for interacting with OptixLog API.

Context Manager Support

The client supports Python’s context manager protocol:

with optixlog.run("my_run") as client:
    # Use client here
    pass
# Automatic cleanup

Properties

PropertyTypeDescription
is_masterboolTrue if this is the master MPI process.
rankintMPI process rank (0 for master).
sizeintTotal number of MPI processes.
run_idstr | NoneUnique identifier for this run. None for worker processes.
projectstrProject name.
run_namestr | NoneRun name.

Methods

log()

Log metrics (scalars, arrays, or any JSON-serializable data).

result = client.log(step: int, **kwargs) -> Optional[MetricResult]

Parameters:

ParameterTypeDescription
stepintStep number (must be non-negative).
**kwargsAnyArbitrary keyword arguments. Values must be JSON-serializable. NaN/Inf values are automatically rejected.

Returns: MetricResult with success status, or None for worker processes.

Example:

result = client.log(step=0, loss=0.5, accuracy=0.95)
if result and result.success:
    print(f"✓ Logged {len(result.metrics)} metrics")

log_image()

Log a PIL Image.

result = client.log_image(key: str, pil_image: Image.Image, meta: Optional[Dict[str, Any]] = None) -> Optional[MediaResult]

Parameters:

ParameterTypeDescription
keystrUnique identifier for this image.
pil_imagePIL.Image.ImagePIL Image object to upload.
metaDict[str, Any] | NoneOptional metadata dictionary.

Returns: MediaResult with URL and file size, or None for worker processes.

Example:

from PIL import Image
img = Image.open("plot.png")
result = client.log_image("my_plot", img, meta={"title": "Results"})
if result:
    print(f"✓ Uploaded! URL: {result.url}")

log_file()

Log a file (CSV, HDF5, JSON, or any file type).

result = client.log_file(key: str, path: str, content_type: Optional[str] = None, meta: Optional[Dict[str, Any]] = None) -> Optional[MediaResult]

Parameters:

ParameterTypeDescription
keystrUnique identifier for this file.
pathstrPath to the file to upload.
content_typestr | NoneMIME type. Auto-detected if None.
metaDict[str, Any] | NoneOptional metadata dictionary.

Returns: MediaResult with URL and file size, or None for worker processes.

Example:

result = client.log_file("results", "data.csv", "text/csv")
if result:
    print(f"✓ Uploaded {result.file_size / 1024:.1f} KB")

log_batch()

Log multiple metrics in parallel.

result = client.log_batch(metrics_list: List[Dict[str, Any]], max_workers: int = 4) -> Optional[BatchResult]

Parameters:

ParameterTypeDescription
metrics_listList[Dict[str, Any]]List of dictionaries, each with step and metric key-value pairs.
max_workersintNumber of parallel workers for upload.

Returns: BatchResult with success statistics, or None for worker processes.

Example:

metrics = [
    {"step": 0, "loss": 0.5, "accuracy": 0.9},
    {"step": 1, "loss": 0.4, "accuracy": 0.92},
    {"step": 2, "loss": 0.3, "accuracy": 0.95},
]
result = client.log_batch(metrics)
print(f"Success rate: {result.success_rate:.1f}%")

Helper Methods (Added Automatically)

These methods are automatically added to the client when initialized. They provide zero-boilerplate logging for common tasks.

log_matplotlib()

Log a matplotlib figure directly (no PIL conversion needed!).

result = client.log_matplotlib(key: str, fig, meta: Optional[Dict[str, Any]] = None) -> Optional[MediaResult]

Example:

import matplotlib.pyplot as plt
 
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
result = client.log_matplotlib("my_plot", fig)
# That's it! No PIL conversion needed.

log_plot()

Create and log a plot from data in one call.

result = client.log_plot(
    key: str,
    x_data: Union[List, np.ndarray],
    y_data: Union[List, np.ndarray],
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    figsize: Tuple[int, int] = (8, 6),
    style: str = '-',
    meta: Optional[Dict[str, Any]] = None
) -> Optional[MediaResult]

Example:

x = np.linspace(0, 10, 100)
y = np.sin(x)
result = client.log_plot("sine_wave", x, y, 
                          title="Sine Wave",
                          xlabel="X", 
                          ylabel="Y")

log_array_as_image()

Convert a numpy array to a heatmap and log it.

result = client.log_array_as_image(
    key: str,
    array: np.ndarray,
    cmap: str = 'viridis',
    title: Optional[str] = None,
    colorbar: bool = True,
    figsize: Tuple[int, int] = (8, 6),
    meta: Optional[Dict[str, Any]] = None
) -> Optional[MediaResult]

Example:

field = np.random.rand(100, 100)
result = client.log_array_as_image("field_snapshot", field, 
                                     cmap='hot', 
                                     title="E-field")

log_histogram()

Create and log a histogram.

result = client.log_histogram(
    key: str,
    data: Union[List, np.ndarray],
    bins: int = 50,
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: str = "Count",
    figsize: Tuple[int, int] = (8, 6),
    meta: Optional[Dict[str, Any]] = None
) -> Optional[MediaResult]

Example:

data = np.random.normal(0, 1, 1000)
result = client.log_histogram("residuals", data, bins=100)

log_scatter()

Create and log a scatter plot.

result = client.log_scatter(
    key: str,
    x_data: Union[List, np.ndarray],
    y_data: Union[List, np.ndarray],
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    figsize: Tuple[int, int] = (8, 6),
    s: int = 20,
    alpha: float = 0.7,
    meta: Optional[Dict[str, Any]] = None
) -> Optional[MediaResult]

Example:

result = client.log_scatter("correlation", x_vals, y_vals)

log_multiple_plots()

Create and log multiple lines on the same plot.

result = client.log_multiple_plots(
    key: str,
    plots_data: List[Tuple[Union[List, np.ndarray], Union[List, np.ndarray], str]],
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    figsize: Tuple[int, int] = (10, 6),
    meta: Optional[Dict[str, Any]] = None
) -> Optional[MediaResult]

Example:

result = client.log_multiple_plots("comparison", [
    (steps, train_loss, "Train"),
    (steps, val_loss, "Validation"),
], title="Loss Curves")

MPI Methods

get_mpi_info()

Get information about the current MPI environment.

info = client.get_mpi_info() -> Dict[str, Any]

Returns: Dictionary with is_master, rank, size, has_mpi.

barrier()

MPI barrier synchronization.

client.barrier()

broadcast_run_id()

Broadcast run_id from master to all workers.

client.broadcast_run_id()

Task Methods

add_run_to_task()

Manually link a run to a task.

client.add_run_to_task(run_id: str, task_id: str)

Query Functions

These functions allow you to programmatically access your logged data.

list_runs()

List recent runs, optionally filtered by project.

runs = optixlog.list_runs(api_url: str, api_key: str, project: Optional[str] = None, limit: int = 10) -> List[RunInfo]

Example:

import optixlog
 
runs = optixlog.list_runs(
    api_url="https://backend.optixlog.com",
    api_key="your_key",
    project="MyProject",
    limit=5
)
for run in runs:
    print(f"{run.name}: {run.run_id}")

get_run()

Get details about a specific run.

run = optixlog.get_run(api_url: str, api_key: str, run_id: str) -> Optional[RunInfo]

Example:

run = optixlog.get_run(api_url, api_key, "run_abc123")
print(f"Config: {run.config}")

get_artifacts()

Get list of artifacts (images, files) for a run.

artifacts = optixlog.get_artifacts(api_url: str, api_key: str, run_id: str) -> List[ArtifactInfo]

Example:

artifacts = optixlog.get_artifacts(api_url, api_key, "run_abc123")
for artifact in artifacts:
    print(f"{artifact.key}: {artifact.url}")

download_artifact()

Download an artifact to a local file.

success = optixlog.download_artifact(api_url: str, api_key: str, media_id: str, output_path: str) -> bool

Example:

success = optixlog.download_artifact(
    api_url, api_key, "media_abc123", "output/plot.png"
)

get_metrics()

Get all metrics logged for a run.

metrics = optixlog.get_metrics(api_url: str, api_key: str, run_id: str) -> Dict[str, List[Any]]

Returns: Dictionary of metric_name -> list of (step, value) tuples.

Example:

metrics = optixlog.get_metrics(api_url, api_key, "run_abc123")
for name, values in metrics.items():
    print(f"{name}: {len(values)} data points")

compare_runs()

Compare metrics across multiple runs.

comparison = optixlog.compare_runs(api_url: str, api_key: str, run_ids: List[str]) -> Optional[ComparisonResult]

Example:

comparison = optixlog.compare_runs(api_url, api_key, ["run1", "run2", "run3"])
print(f"Common metrics: {comparison.common_metrics}")

list_projects()

List all projects.

projects = optixlog.list_projects(api_url: str, api_key: str) -> List[ProjectInfo]

Example:

projects = optixlog.list_projects(api_url, api_key)
for project in projects:
    print(f"{project.name}: {project.run_count} runs")

Helper Functions

get_mpi_info()

Get current MPI environment information (module-level function).

info = optixlog.get_mpi_info() -> Dict[str, Any]

Returns: Dictionary with is_master, rank, size, has_mpi.

is_master_process()

Check if the current process is the master process.

is_master = optixlog.is_master_process() -> bool

create_project()

Create a new project programmatically.

project_id = optixlog.create_project(api_url: str, api_key: str, project_name: str) -> Optional[str]

Return Types

MetricResult

Result from logging metrics.

@dataclass
class MetricResult:
    step: int
    metrics: Dict[str, Any]
    success: bool
    timestamp: Optional[datetime] = None
    error: Optional[str] = None

Usage:

result = client.log(step=0, loss=0.5)
if result and result.success:
    print(f"✓ Logged at {result.timestamp}")

MediaResult

Result from logging images or files.

@dataclass
class MediaResult:
    key: str
    success: bool
    media_id: Optional[str] = None
    url: Optional[str] = None
    file_size: Optional[int] = None
    content_type: Optional[str] = None
    error: Optional[str] = None

Usage:

result = client.log_image("plot", img)
if result:
    print(f"✓ View at: {result.url}")
    print(f"  Size: {result.file_size / 1024:.1f} KB")

BatchResult

Result from batch operations.

@dataclass
class BatchResult:
    total: int
    successful: int
    failed: int
    results: List[Any]
    errors: List[str]
    
    @property
    def success_rate(self) -> float:
        """Success rate as percentage"""

Usage:

result = client.log_batch(metrics_list)
print(f"Success rate: {result.success_rate:.1f}%")

RunInfo

Information about a run.

@dataclass
class RunInfo:
    run_id: str
    name: Optional[str]
    project_id: str
    project_name: str
    config: Dict[str, Any]
    created_at: str
    status: str = "running"

ArtifactInfo

Information about an uploaded artifact.

@dataclass
class ArtifactInfo:
    media_id: str
    key: str
    kind: str
    url: str
    content_type: str
    file_size: Optional[int] = None
    created_at: Optional[str] = None
    meta: Dict[str, Any] = field(default_factory=dict)

ProjectInfo

Information about a project.

@dataclass
class ProjectInfo:
    project_id: str
    name: str
    created_at: str
    run_count: Optional[int] = None

ComparisonResult

Result from comparing multiple runs.

@dataclass
class ComparisonResult:
    runs: List[RunInfo]
    common_metrics: List[str]
    metrics_data: Dict[str, Dict[str, List[float]]]  # metric -> run_id -> values

Exceptions

OxInvalidTaskError

Raised when a task operation fails.

from optixlog import OxInvalidTaskError
 
try:
    client.add_run_to_task("run_id", "invalid_task_id")
except OxInvalidTaskError as e:
    print(f"Task error: {e}")

ValidationError

Raised when input validation fails (NaN/Inf values, invalid types, etc.).

from optixlog import ValidationError
 
try:
    client.log(step=0, value=float('nan'))
except ValidationError as e:
    print(f"Validation error: {e}")

ValueError

Raised for various errors:

  • Missing API key
  • Project not found
  • Authentication failures
  • Server errors

Environment Variables

VariableDescriptionDefault
OPTIX_API_KEYAPI key for authenticationNone (required)
OPTIX_API_URLAPI endpoint URLhttps://backend.optixlog.com
OPTIX_PROJECTDefault project name"dev"

Next Steps

SDK Advanced UsageSDK Examples