SOLAR Adapter

This repository is the OptiProfiler-side adapter plan for bbopt/solar, a solar thermal power plant simulator for black-box optimization benchmarking.

The adapter is intentionally separate from optiprofiler-platform and from the upstream SOLAR repository. Its job is to maintain a reviewed SOLAR snapshot, record its exact upstream revision, and expose a stable protocol that Python and MATLAB OptiProfiler integrations can call.

Current Status

This adapter now provides the common SOLAR executable protocol, curated metadata, smoke tests, and a slim runtime export for language-specific OptiProfiler wrappers.

• Upstream: https://github.com/bbopt/solar
• Upstream default branch: master
• Upstream license file: LGPL-2.1; current source headers mention LGPL version 3 or later. Keep both the license file and source notices in distributed runtime snapshots.
• Current upstream commit recorded at scaffold time: dda8fd7f98d4392aa07b3e3056888624a00712a0
• Wrapper status: solar_python and solar_matlab vendor the slim runtime exported by this adapter and expose the public OptiProfiler problem-library name solar.
• Enabled scalar first-pass instances: SOLAR 1-7 and 10.
• Disabled for now: SOLAR 8-9 are multiobjective; SOLAR 11 returns empty output at the documented initial point in the current upstream revision.

What "Pin Upstream" Means

For SOLAR, "pin" means normal builds and tests always use the exact commit in upstream/manifest.json. A scheduled workflow may fetch and test a newer candidate, but it only publishes a report and an upstream-update issue. It cannot update this repository or dispatch changes to the language wrappers. Promotion is an explicit maintainer operation after source, license, build, smoke, and metadata review.

Repository Shape

solar_adapter/
├── .github/workflows/sync_solar.yml
├── build/                  # generated, ignored
├── docs/
│   ├── optiprofiler_mapping.md
│   └── protocol.md
├── scripts/
│   ├── build_solar.sh
│   ├── check_upstream.py
│   ├── export_runtime.sh
│   ├── smoke_solar.py
│   └── sync_solar.sh
├── solar_adapter/
│   ├── __init__.py
│   ├── metadata.py
│   └── runner.py
├── tests/
│   └── README.md
└── upstream/
    ├── .gitkeep
    └── manifest.json   # generated by scripts/sync_solar.sh

The upstream/solar/ source checkout is generated by sync scripts and should not be committed unless we later decide to vendor selected files after a license review.

Slim Runtime Policy

The upstream SOLAR checkout is large mostly because it includes upstream test data and Git history. Those files are useful for upstream development, but they are not part of the OptiProfiler runtime.

scripts/export_runtime.sh builds and exports a slim runtime containing only:

• bin/solar or bin/solar.exe, when building a local smoke-test artifact;
• src/*.cpp, src/*.hpp, and src/makefile, so CI or a server can rebuild;
• LICENSE, upstream README, and upstream/manifest.json;
• generated OptiProfiler metadata under metadata/.

Language-specific repositories should vendor this slim runtime but should not commit the generated executable, object files, upstream tests/, or upstream .git directory. In other words, benchmark data that belongs to SOLAR upstream stays upstream; our wrapper repositories carry only what is needed to run the selected OptiProfiler problems reproducibly.

The build is checked on Linux, macOS, and Windows in CI. Windows jobs use MSYS2/MinGW so the same upstream makefile can be exercised with make and g++; the resulting executable name is solar.exe.

Before compiling or exporting the slim runtime, the adapter applies a small compatibility patch to the transient checkout: upstream currently has one unqualified isnan call that macOS accepts but Linux g++ rejects, so the adapter rewrites it to std::isnan. The upstream commit remains recorded in upstream/manifest.json.

Automation

.github/workflows/sync_solar.yml checks upstream SOLAR on a schedule and on manual dispatch. When a newer commit exists, it builds and smoke-tests that candidate in the temporary runner workspace, uploads the generated manifest and report, and creates or updates an issue. It never commits the candidate or dispatches runtime updates to solar_python or solar_matlab.

.github/workflows/ci.yml always checks out the commit already pinned in upstream/manifest.json; it does not test a moving default branch.

Why Not solar_python and solar_matlab Immediately?

SOLAR is a C++ executable interface, not a Python-native or MATLAB-native problem library. The common piece is the executable build, metadata, and stdout parser. Python and MATLAB wrappers should share that protocol.

A likely final organization is:

• solar_adapter: common upstream sync, build, metadata, CLI protocol, smoke tests, license/citation record.
• solar_python: Python OptiProfiler wrapper around the adapter protocol.
• solar_matlab: MATLAB OptiProfiler wrapper around the adapter protocol.

Starting with solar_adapter keeps the executable and legal/provenance story consistent before language-specific repositories split off.

How SOLAR Is Called

According to upstream SOLAR v1.0.8:

solar pb_id x.txt -seed=S -fid=F -rep=R

• pb_id: SOLAR problem id.
• x.txt: text file containing one vector per line, values separated by spaces.
• seed: deterministic integer seed by default; diff makes stochastic runs vary between calls and is not suitable for default reproducible benchmarks.
• fid: fidelity in [0, 1]; 1.0 is the truth.
• rep: replication count/probability for stochastic outputs.

The first adapter target should use deterministic, single-objective, full-fidelity calls:

solar pb_id x.txt -seed=0 -fid=1.0 -rep=1

Mapping to OptiProfiler

OptiProfiler expects a problem loader to return a Problem object:

• fun(x) -> float
• x0 -> vector
• optional xl, xu
• optional aub, bub, aeq, beq
• optional cub(x) <= 0
• optional ceq(x) == 0

SOLAR returns objective and constraints from one simulator call, so wrappers should cache the most recent evaluation at a given x and share it between fun, cub, and ceq.

See docs/protocol.md and docs/optiprofiler_mapping.md.

License and Citation

SOLAR ships an LGPL-2.1 license file in the upstream snapshot, while current source headers mention LGPL version 3 or later. This adapter should keep SOLAR as an upstream dependency, preserve license notices, and record the upstream commit in upstream/manifest.json for every sync.

Any distributed artifact that includes SOLAR source or binaries should include:

• SOLAR license text and copyright notices;
• the upstream repository URL;
• the exact upstream commit or release;
• instructions for obtaining corresponding source.