Sessions and audit log¶

A session holds your variables, results, model settings and audit trail. This page saves it to a file, opens it again, and exports the audit log that records how the campaign got where it is.

The header on a simulated session. Save and Save As… sit in one split button; before the first save it reads "Not saved to a file".

Where a session lives¶

The ALchemist server holds the session while it runs, under an ID. The server also writes the session to its own cache/sessions folder after every change, and reads it back, rebuilding its model, the first time its ID is used after a restart. If the model cannot be rebuilt, for example because the training fails on the saved data, the session loads without a model and keeps its training call, so the next reload tries it again; train the model again to get one back. A saved file is the copy you keep, share or open on another server, and joining is how a second browser reaches the live session.

1. Start, open or join a session¶

The header shows the session's name ("Untitled Session" until you give it one), the first eight characters of the ID and a count such as "4V · 16E" (variables and experiments). The copy button beside it copies the full ID, and a link of the form ?session=<ID> opens that session directly. Clear closes the session in this browser and forgets its linked files; when the session has changes not yet saved to a file, it asks first. It does not delete the session from the server, so the same ID joins it again.

Reloading the page, or quitting and relaunching the server, reopens the session this browser last created, loaded, restored or joined, still linked to its file. A ?session=<ID> address opens that session instead. If the server no longer has the session, the app shows the welcome screen. A session that is reopened, joined or loaded brings its model settings with it: the Model tab shows them.

2. Save¶

Choose Save, or press ⌘S (Ctrl+S on Windows and Linux). The arrow beside it opens a menu with Save and Save As… (⇧⌘S, or Ctrl+Shift+S). The shortcuts work whenever a session is open, and the browser's own save is turned off for them.

The link between a session and its file belongs to this browser, not to the server. After a reload Chrome asks again for permission to write the file. If the write fails, for example because the file was moved, a message says so and offers Save As….

The file is named after the session title: <title>.json. Characters that file names forbid become _, a title over 120 characters is cut, and a session with no title, or the default "Untitled Session", uses alchemist_session_ and the first eight characters of its ID. Define variables describes the same behaviour for the variables file.

The dot appears after any change to what the file holds, such as variables, results, training or staged points, and not after previewing a design, plotting or predicting. Closing or reloading the page with unsaved changes asks you to confirm. As a safety net, while a session has unsaved changes the app copies it to the server's recovery folder every 30 seconds. A page opened without ?session= offers to restore the newest copy of a session this browser created, joined, loaded or restored (it remembers the last 50), other than the one it reopens; the restored copy becomes a new session, which takes over the backup. A successful save clears it.

3. Export the audit log¶

Choose Export Log. Chrome and Edge on https or localhost show a save dialog; other browsers download. The suggested name is <title>_audit_log.md, built from the title in the same way. Nothing is linked, so each export asks again.

The audit log only ever has entries added. The exported Markdown has four parts.

Entries are added when you generate or stage a design, ask for a suggestion, and record results with Retrain model (once, after saving) ticked. The session file also keeps entries that the Markdown leaves out: configuration changes, each completed experiment with the suggested and the actual point, and pause requests.

4. What the file contains¶

The session file is JSON: metadata, search space, data, work queue, audit log, and the model's settings and training arguments, but not the fitted model. Python's load_session retrains the model from those settings, so you get back the model they give on that data. The file does not record random seeds you did not set. For a methods section, export the audit log and keep the session file beside it. The keys are listed in File formats.

from alchemist_core import OptimizationSession

session = OptimizationSession()
session.update_metadata(name="Pd screening", description="Synthetic example", tags=["demo"])
session.add_variable("temperature", "real", bounds=(200.0, 300.0), unit="°C")
session.add_variable("pressure", "real", bounds=(20.0, 80.0), unit="bar")
for p in session.generate_initial_design("lhs", n_points=8, random_seed=1):
    y = -((p["temperature"] - 250) / 50) ** 2 - ((p["pressure"] - 50) / 30) ** 2
    session.add_experiment(p, output=y, reason="Initial Design")
session.train_model(backend="botorch")

session.save_session("pd_screening.json")
restored = OptimizationSession.load_session("pd_screening.json")
print(restored.metadata.name, len(restored.experiment_manager.get_data()), restored.model is not None)

suggestion = session.suggest_next(strategy="EI", goal="maximize")
session.lock_acquisition(
    strategy="EI",
    parameters={"goal": "maximize"},
    suggestions=suggestion.to_dict("records"),
    notes="Round 1",
)
print([entry.entry_type for entry in session.audit_log.get_entries()])

with open("pd_screening_audit_log.md", "w") as handle:
    handle.write(session.export_audit_markdown())

POST /api/v1/sessions

PATCH /api/v1/sessions/{session_id}/metadata
Content-Type: application/json

{"name": "Pd screening", "description": "Synthetic example", "tags": ["demo"]}