TauOpt quickstart: Branin, locally then hosted

Two cells of real optimization:

1. Local (repository access): the open engine runs in-process, installed from a clone (git clone https://github.com/talariasci/tauopt && cd tauopt && pip install "./python[all]"). The package is not distributed during the closed beta: the PyPI name holds a placeholder until the public release, and the repository is private (request access at tauopt.com).

2. Hosted beta (nothing to install; run the first code cell, the Branin function, then skip section 1 and run section 2): the same loop against your beta-lane URL with your tau_ token, over plain HTTP from Python’s standard library; python/examples/branin_rest.py is the script form. After the public release the Python client (Client(base_url=..., token=...)) is the one-line alternative.

Branin is the classic 2-D test function; its global minimum is approximately 0.3979.

import math


def branin(x1: float, x2: float) -> float:
    a, b, c = 1.0, 5.1 / (4 * math.pi**2), 5 / math.pi
    r, s, t = 6.0, 10.0, 1 / (8 * math.pi)
    return a * (x2 - b * x1**2 + c * x1 - r) ** 2 + s * (1 - t) * math.cos(x1) + s


BRANIN_PARAMETERS = [
    {"name": "x1", "type": "double", "bounds": [-5.0, 10.0]},
    {"name": "x2", "type": "double", "bounds": [0.0, 15.0]},
]

1. Local engine

Client(driver="local") runs the full engine in-process: no server, no account. The default policy starts space-filling and moves to GP-based suggestions as observations accumulate.

try:
    from tauopt import Client, OptimizationComplete
except ImportError:
    print("tauopt is not installed; skipping the local half (the closed beta runs section 2)")
else:
    local = Client(driver="local")
    exp = local.create_experiment(
        name="branin-local",
        parameters=BRANIN_PARAMETERS,
        metric={"name": "branin", "objective": "minimize"},
        observation_budget=30,
    )
    for _ in range(30):
        try:
            s = local.suggest(exp.id)
        except OptimizationComplete:
            break  # a terminal completion (today: proven exhaustion, finite spaces only)
        local.observe(
            exp.id,
            suggestion_id=s.id,
            value=branin(s.assignments["x1"], s.assignments["x2"]),
        )
    print(local.best(exp.id))

count=1 data=(BestObservation(assignments={'x1': 9.382630586713901, 'x2': 2.570797868722037}, value=0.4236073059843637, values=None),)

2. Hosted beta lane

Run the same loop over plain HTTP against your beta-lane URL (the isolated beta deployment you were given at signup); nothing beyond the standard library is imported. Your tau_ token was shown once when your account was created – store it in an env var or a secrets manager, never in a notebook cell. (Tokens are lane-scoped: a beta token only works on the beta lane.) Without both TAUOPT_BASE_URL and TAUOPT_TOKEN in the environment the next cell prints one line naming the missing one and skips, so the notebook runs end to end in CI. The cell stops at the first error (a rejected token is urllib.error.HTTPError: HTTP Error 401: Unauthorized); python/examples/branin_rest.py is the same loop with the service’s answers handled. Each call below is one route of the REST API: create, then per round a suggestion and an observation, then the best, then the archive.

import json
import os
import urllib.request

BASE_URL, token = os.environ.get("TAUOPT_BASE_URL"), os.environ.get("TAUOPT_TOKEN")
if not BASE_URL or not token:
    missing = "/".join(n for n, v in (("TAUOPT_BASE_URL", BASE_URL), ("TAUOPT_TOKEN", token)) if not v)
    print(f"{missing} not set; skipping the hosted half (export TAUOPT_BASE_URL=https://api.tauopt.com and a TAUOPT_TOKEN minted at app.tauopt.com/settings/tokens)")
else:

    def call(method, path, body=None):
        req = urllib.request.Request(
            BASE_URL.rstrip("/") + path,
            data=None if body is None else json.dumps(body).encode(),
            method=method,
            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        )
        with urllib.request.urlopen(req, timeout=120) as r:
            return json.loads(r.read()) if r.status != 204 else None

    exp = call(
        "POST",
        "/v1/experiments",
        {
            "name": "branin-hosted",
            "parameters": BRANIN_PARAMETERS,
            "metric": {"name": "branin", "objective": "minimize"},
            "observation_budget": 30,
        },
    )
    for _ in range(30):
        s = call("POST", f"/v1/experiments/{exp['id']}/suggestions", {})
        call(
            "POST",
            f"/v1/experiments/{exp['id']}/observations",
            {"suggestion_id": s["id"], "value": branin(s["assignments"]["x1"], s["assignments"]["x2"])},
        )
    print(call("GET", f"/v1/experiments/{exp['id']}/best_assignments"))
    call("DELETE", f"/v1/experiments/{exp['id']}")

TAUOPT_BASE_URL/TAUOPT_TOKEN not set; skipping the hosted half (export TAUOPT_BASE_URL=https://api.tauopt.com and a TAUOPT_TOKEN minted at app.tauopt.com/settings/tokens)

Notes for beta collaborators

• Default quotas: 1,000 suggestions per rolling 24 h and 25 active experiments. Suggestion-quota 429s carry Retry-After (when the rolling window frees); active-experiment 429s do not; archive an experiment instead. The quotas never throttle reads or observations, so a running loop can always land its results; the beta lane’s pre-authentication rate limits (on every /v1 request: the lane’s bucket of 150 per second with a burst of 300, every caller together, and the per-credential bounds of eight requests in flight, 40 per second with a burst of 80, and 15 history-sized reads per second with a burst of 30) are the 429s a read or an observe can meet (rate_limited, credential_rate_limited), and the client’s bounded retries honor their 1-second Retry-After.

• Archive finished experiments with DELETE /v1/experiments/{id} (the cell above does; the Python client’s client.archive_experiment(exp.id) is the same call); the active-experiment cap counts live ones only, and archived experiments stay readable.

• Something broken or surprising? Reply on your invite thread.