Closed-Loop Manifold Active Learning with AFL Servers

This case study runs the manifold active learning campaign in a format amenable with the usage of AFL’s microservice concept:

1. Connect to the services (Tiled, instrument, agent).

2. Specify the problem (campaign ID, components, bounds, number of iterations).

3. Configure data collection: tell the agent how to find each measurement in Tiled.

4. Convert agent suggestions into measurement targets.

5. Run one experiment: the instrument server measures and writes each exposure to Tiled, the agent appends the entry IDs to its dataset.

6. Seed the campaign with the initial composition.

7. Build the pipeline on the agent server.

8. Close the loop: predict, measure the suggestion, append, repeat.

• The virtual instrument ProteinGlycerolTemperaturePhaseMap runs as an AFL-automation APIServer, exactly like a hardware driver. AFL.double_agent.VirtualInstrumentDriver serves whichever virtual instrument the instrument key of its --config file names (phase_map_instrument.json here, which also carries the instrument’s instrument_overrides), takes that instrument’s class name as the server and driver_name, and exposes every public method of the instrument as a task: this notebook assigns it a sample with set_sample and enqueues one expose task per temperature; the server writes the returned dataset to Tiled with the sample identity and campaign in its attributes and reports the Tiled entry ID.

• The agent, a DoubleAgentDriver server, reads the entries by ID, fits the pipeline and returns the next composition and temperature profile.

Prerequisites

Three services must be running, all pointed at the same Tiled instance through ~/.afl/config.json (tiled_server, tiled_api_key and the "ports" of the two drivers):

Service	Example address	Launch
Tiled	http://localhost:8000	tiled serve config config.yml (AFL-automation tiled/config.yml with single_user_api_key set)
ProteinGlycerolTemperaturePhaseMap	localhost:5052	python -m AFL.double_agent.VirtualInstrumentDriver --config phase_map_instrument.json in this directory
DoubleAgentDriver	localhost:5050	PYTHONPATH=. python <AFL-agent>/AFL/double_agent/AgentDriver.py in this directory

The agent server is launched from this directory because the pipeline holds lambdas, the SRSF manifold and the simulator, which have no JSON form.

The settings, the acquisition scores and the Pipeline are defined in helpers.py in this directory, which this notebook and the companion notebook import. The notebook sends the JSON of the pipeline, in which those objects appear as references, and names the module as the pipeline’s environment; the agent server imports it to obtain the live objects behind the references.

The analysis environment needs AFL.double_agent with the manifold extra, AFL.automation and the Tiled client.

Set Up the Environment

Import the client of the AFL servers, the Tiled helper and, from helpers.py, the settings and functions of the campaign. Everything the pipeline needs lives in that module so that the notebook and the agent server agree on it.

# Uncomment this cell if you need to install AFL-agent with the ``manifold`` extra
# (torch, gpytorch, pyro-ppl, botorch, geoopt, alphashape, trimesh) and AFL-automation.
# !pip install "AFL-agent[manifold] @ git+https://github.com/usnistgov/afl-agent"
# !pip install "AFL-automation @ git+https://github.com/usnistgov/afl-automation"

import uuid

import numpy as np

from AFL.automation.APIServer.Client import Client
from AFL.automation.shared.tiled import get_tiled_client

from helpers import BOUNDS_T, LIMITS, XY, pipeline, xarray_to_target  # settings, scores and pipeline, see helpers.py in this folder

np.set_printoptions(precision=3, suppress=True)

/home/knv2/codebase/AFL-bioformulations/.venv/lib/python3.11/site-packages/torch/cuda/__init__.py:182: UserWarning: CUDA initialization: The NVIDIA driver on your system is too old (found version 11040). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/index.aspx Alternatively, go to: https://pytorch.org to install a PyTorch version that has been compiled with your version of the CUDA driver. (Triggered internally at /pytorch/c10/cuda/CUDAFunctions.cpp:119.)
  return torch._C._cuda_getDeviceCount() > 0

# services
INSTRUMENT_HOST, INSTRUMENT_PORT = "localhost", 5052  # ProteinGlycerolTemperaturePhaseMap APIServer
AGENT_HOST, AGENT_PORT = "localhost", 5050  # DoubleAgentDriver APIServer
USERNAME = "afl-agent"

# campaign
N_ITERATIONS = 4  # compositions (one temperature profile each) acquired after the seed
INITIAL_COMPOSITION = {"protein": 40.0, "glycerol": 5.0}  # the one composition measured before the campaign
INITIAL_TEMPERATURES = [5.0, 10.0, 20.0, 30.0, 40.0, 45.0]  # ... and the temperatures it is measured at
SEED = 1000

# how the instrument's entries are identified in Tiled
INSTRUMENT_NAME = "ProteinGlycerolTemperaturePhaseMap"  # driver_name written to every Tiled entry
EXPOSE_TASK = "expose"  # task_name written to every Tiled entry
SAMPLE_DIM = "sample"
INPUT_VARIABLES = ["design_space", "phases", "composition"]  # pulled from each entry into the agent dataset
PIPELINE_ENVIRONMENT = "helpers"  # module importable on the agent server that defines ``pipeline``

Connect to the Services

get_tiled_client reads the Tiled server and API key from ~/.afl/config.json, the same configuration the servers use. Create a client for the instrument and the agent and log in to both.

tiled = get_tiled_client()

instrument = Client(INSTRUMENT_HOST, port=INSTRUMENT_PORT)
agent = Client(AGENT_HOST, port=AGENT_PORT)
for client in (instrument, agent):
    client.login(USERNAME)

instrument.enqueue(task_name="status", interactive=True)["return_val"]

['Idle', 'Configurations Loaded=3', 'Phases Traced=3', 'Noise Level=0.0']

Specify the Optimization Problem

Use one campaign ID everywhere. A unique campaign ID prevents measurements from different runs from being combined. The composition components and their bounds are those of the instrument; the temperature range is the one the stage-2 profile is mapped onto.

campaign_id = f"manifold-{uuid.uuid4().hex[:8]}"
components = XY  # composition components searched in stage 1: protein, glycerol
bounds = {c: LIMITS[c] for c in components}
np.random.seed(SEED)
campaign_id, bounds, BOUNDS_T

('manifold-95dad5a5',
 {'protein': (0.5, 75.0), 'glycerol': (0.5, 10.0)},
 [0.5, 45.0])

Configure Data Collection

Tell the agent how to find and align the measurements. Every Tiled entry written by the instrument server holds one exposure; driver_name and task_name select the instrument’s expose entries and campaign_id_path points at the campaign attribute that set_sample adds to each of them. The three variables are read from the entry’s dataset and stacked along sample.

input_spec = {
    "campaign_id": campaign_id,
    "sample_dim": SAMPLE_DIM,
    "sources": {
        name: {
            "driver_name": INSTRUMENT_NAME,
            "task_name": EXPOSE_TASK,
            "campaign_id_path": "attrs.AL_campaign_name",
            "source": "dataset",
            "path": name,
        }
        for name in INPUT_VARIABLES
    },
}
agent.enqueue(task_name="setup_data_collection", input_spec=input_spec, interactive=True)["return_val"]

{'campaign_id': 'manifold-95dad5a5',
 'sources': ['design_space', 'phases', 'composition'],
 'started_at': '2026-10-27T19:33:48.676258+00:00',
 'status': 'success'}

Run One Experiment

A target is one composition at several temperatures. Each temperature is one exposure of the instrument: assign the sample identity and campaign with set_sample, enqueue expose, and keep the Tiled entry ID the server reports. The agent then reads the entry by ID; since all three input variables come from the same entry, the same ID is given for each of them.

The phase label of each exposure is read back from Tiled only for the progress report below.

def measure_sample(iteration, target):
    entry_ids = []
    for temperature in target["temperatures"]:
        temperature = float(temperature)
        instrument.enqueue(
            task_name="set_sample",
            sample_name=f"{campaign_id}-sample-{iteration:03d}-T{temperature:.1f}",
            sample_uuid=f"SAM-{uuid.uuid4()}",
            AL_campaign_name=campaign_id,
            interactive=True,
        )
        exposure = instrument.enqueue(
            task_name=EXPOSE_TASK,
            protein=target["protein"],
            glycerol=target["glycerol"],
            temperature=temperature,
            interactive=True,
        )
        entry_id = exposure.get("tiled_entry_id")
        if not entry_id:
            raise RuntimeError(
                f"the instrument server did not write to Tiled (tiled_status={exposure.get('tiled_status')!r}); "
                "check tiled_server and tiled_api_key in ~/.afl/config.json"
            )
        agent.enqueue(
            task_name="append_dataset",
            entries={name: entry_id for name in INPUT_VARIABLES},
            interactive=True,
        )
        entry_ids.append(entry_id)
    return entry_ids


def read_phases(entry_ids):
    return [int(tiled["run_documents"][entry_id]["phases"].read()) for entry_id in entry_ids]

Seed the Campaign

The campaign starts from a single composition measured at six temperatures.

initial_target = {**INITIAL_COMPOSITION, "temperatures": INITIAL_TEMPERATURES}
initial_entry_ids = measure_sample(0, initial_target)
n_measurements = len(initial_entry_ids)
print(f"seed: phases={read_phases(initial_entry_ids)} (n_measurements={n_measurements})")

seed: phases=[1, 1, 1, 0, 0, 0] (n_measurements=6)

Build the Pipeline

pipeline is the manifold pipeline of helpers.py: the DirichletGPExtrapolator phase classifier, the PhaseMapF1Score benchmark against the simulator, BoTorchAcquisition over the composition with composition_score and SRSFHilbertSphereAcquisitionFunction over the temperature profile with profile_score. Its JSON form records the lambdas, the manifold and the simulator as references; initialize_pipeline receives the JSON together with environment, the module the agent server imports to obtain the live objects behind those references.

for i, op in enumerate(pipeline):
    print(i, op.name)

agent.enqueue(
    task_name="initialize_pipeline",
    pipeline=pipeline.to_dict()["ops"],
    name=pipeline.name,
    environment=PIPELINE_ENVIRONMENT,
    interactive=True,
)["exit_state"]

0 Grid-DesignSpace
1 Grid-Composition
2 DirichletGPExtrapolator-PhaseLabels
3 PhaseMapF1Score
4 BoTorchAcquisition-Composition
5 SRSF-TemperatureProfile

'Success!'

Close the Loop

Each call to predict evaluates the accumulated campaign data on the agent server. Retrieve last_results, turn its suggestion into a target, measure it and append the new exposures before requesting another prediction.

The benchmark variables of a result belong to the model fitted before the new batch, so the F1 score reported at iteration i is that of a model trained on i - 1 acquired compositions.

for iteration in range(1, N_ITERATIONS + 1):
    agent.enqueue(task_name="predict", AL_campaign_name=campaign_id, interactive=True)
    results = agent.get_driver_object("last_results")
    target = xarray_to_target(results)

    entry_ids = measure_sample(iteration, target)
    n_measurements += len(entry_ids)

    print(
        f"[{iteration:3d}/{N_ITERATIONS}] protein={target['protein']:6.2f} glycerol={target['glycerol']:5.2f} "
        f"temperatures={[round(float(t), 1) for t in target['temperatures']]} "
        f"phases={read_phases(entry_ids)} "
        f"(n_measurements={n_measurements}) "
        f"f1={results.benchmark_f1.item():.3f} accuracy={results.benchmark_accuracy.item():.3f}"
    )

[  1/4] protein= 72.95 glycerol=10.00 temperatures=[0.5, 3.0, 27.0, 45.0] phases=[1, 1, 1, 0] (n_measurements=10) f1=0.495 accuracy=0.597
[  2/4] protein=  6.29 glycerol= 0.80 temperatures=[0.5, 24.0, 27.0, 45.0] phases=[1, 0, 0, 0] (n_measurements=14) f1=0.505 accuracy=0.603
[  3/4] protein=  4.72 glycerol=10.00 temperatures=[0.5, 21.0, 45.0] phases=[1, 1, 0] (n_measurements=17) f1=0.512 accuracy=0.620
[  4/4] protein= 72.42 glycerol= 0.50 temperatures=[0.5, 18.0, 21.0, 45.0] phases=[2, 1, 1, 0] (n_measurements=21) f1=0.504 accuracy=0.607

After the final iteration, refit on everything measured. PhaseMapF1Score scores the classifier against the simulator, and the agent archives the result dataset in Tiled next to the campaign’s entries.

agent.enqueue(task_name="predict", AL_campaign_name=campaign_id, interactive=True)
results = agent.get_driver_object("last_results")
print(
    f"score: campaign={campaign_id} n_measurements={n_measurements} "
    f"f1={results.benchmark_f1.item():.3f} accuracy={results.benchmark_accuracy.item():.3f}"
)

score: campaign=manifold-95dad5a5 n_measurements=21 f1=0.519 accuracy=0.627

results[["composition_next", "profile_function", "benchmark_f1"]]

<xarray.Dataset> Size: 2kB
Dimensions:           (next_sample: 1, component: 2, profile_t: 100,
                       profile_dim: 1)
Coordinates:
  * component         (component) <U8 64B 'protein' 'glycerol'
  * profile_t         (profile_t) float64 800B 0.0 0.0101 0.0202 ... 0.9899 1.0
Dimensions without coordinates: next_sample, profile_dim
Data variables:
    composition_next  (next_sample, component) float64 16B 73.83 2.059
    profile_function  (profile_t, profile_dim) float64 800B 0.0 4.79e-07 ... 1.0
    benchmark_f1      float64 8B 0.5189
Attributes:
    sample_uuid:       SAM-9bd9e417-7c07-4a54-82de-120fa519b8f1
    ag_uuid:           AG-e508f98e-2584-46c0-9fd2-010eb4f3ccd4
    AL_campaign_name:  manifold-95dad5a5

xarray.Dataset

• Dimensions:
  • next_sample: 1
  • component: 2
  • profile_t: 100
  • profile_dim: 1
• Coordinates: (2)
  • component
    (component)
    <U8
    'protein' 'glycerol'

    array(['protein', 'glycerol'], dtype='<U8')

  • profile_t
    (profile_t)
    float64
    0.0 0.0101 0.0202 ... 0.9899 1.0

    array([0.      , 0.010101, 0.020202, 0.030303, 0.040404, 0.050505, 0.060606,
           0.070707, 0.080808, 0.090909, 0.10101 , 0.111111, 0.121212, 0.131313,
           0.141414, 0.151515, 0.161616, 0.171717, 0.181818, 0.191919, 0.20202 ,
           0.212121, 0.222222, 0.232323, 0.242424, 0.252525, 0.262626, 0.272727,
           0.282828, 0.292929, 0.30303 , 0.313131, 0.323232, 0.333333, 0.343434,
           0.353535, 0.363636, 0.373737, 0.383838, 0.393939, 0.40404 , 0.414141,
           0.424242, 0.434343, 0.444444, 0.454545, 0.464646, 0.474747, 0.484848,
           0.494949, 0.505051, 0.515152, 0.525253, 0.535354, 0.545455, 0.555556,
           0.565657, 0.575758, 0.585859, 0.59596 , 0.606061, 0.616162, 0.626263,
           0.636364, 0.646465, 0.656566, 0.666667, 0.676768, 0.686869, 0.69697 ,
           0.707071, 0.717172, 0.727273, 0.737374, 0.747475, 0.757576, 0.767677,
           0.777778, 0.787879, 0.79798 , 0.808081, 0.818182, 0.828283, 0.838384,
           0.848485, 0.858586, 0.868687, 0.878788, 0.888889, 0.89899 , 0.909091,
           0.919192, 0.929293, 0.939394, 0.949495, 0.959596, 0.969697, 0.979798,
           0.989899, 1.      ])

• Data variables: (3)
  • composition_next
    (next_sample, component)
    float64
    73.83 2.059

    description :

    Next sample point(s) found by maximizing the acquisition score with BoTorch

    name :

    BoTorchAcquisition-Composition

    input_variable :

    ['composition', 'composition_grid', 'phase_model']

    output_variable :

    composition_next

    input_prefix :

    None

    output_prefix :

    composition

    _stored_args :

    {'feature_input_variable': 'composition', 'grid_variable': 'composition_grid', 'bounds': {'protein': [0.5, 75.0], 'glycerol': [0.5, 10.0]}, 'grid_dim': 'comp_grid', 'model_variable': None, 'best_f_variable': None, 'objective_direction': 'maximize', 'output_prefix': 'composition', 'output_variable': 'composition_next', 'decision_rtol': 0.05, 'excluded_comps_variables': None, 'excluded_comps_dim': None, 'exclusion_radius': 0.001, 'count': 1, 'acquisition': <function <lambda> at 0x7fbc24d53ec0>, 'num_restarts': 8, 'raw_samples': 64, 'is_simplex': False, 'name': 'BoTorchAcquisition-Composition'}

    input_variables :

    ['composition']

    sample_dim :

    AF_sample

    random_fraction :

    0.0

    model_uri :

    None

    acquisition_function :

    ScoreFunctionAcquisition()

    _provided :

    {}

    array([[73.827,  2.059]])

  • profile_function
    (profile_t, profile_dim)
    float64
    0.0 4.79e-07 ... 0.9351 1.0

    bounds_t :

    [0.5, 45.0]

    description :

    Optimal function on [0, 1] (values in [0, 1])

    name :

    SRSF-TemperatureProfile

    input_variable :

    ['phase_model', 'composition_next']

    output_variable :

    profile_function

    input_prefix :

    None

    output_prefix :

    profile

    _stored_args :

    {'manifold': SRSF Hilbert Sphere manifold, 'acquisition': <function <lambda> at 0x7fbc24cf1ee0>, 'bounds_t': [0.5, 45.0], 'output_prefix': 'profile', 'n_restarts': 8, 'n_iterations': 100, 'learning_rate': 0.1, 'device': 'cpu', 'name': 'SRSF-TemperatureProfile'}

    acquisition_function :

    <function SRSFHilbertSphereAcquisitionFunction.build_acquisition.<locals>.score at 0x7fbc2490cc20>

    array([[0.   ],
           [0.   ],
           [0.   ],
           [0.   ],
           [0.   ],
           [0.   ],
           [0.   ],
           [0.002],
           [0.008],
           [0.023],
           [0.06 ],
           [0.129],
           [0.238],
           [0.378],
           [0.524],
           [0.61 ],
           [0.625],
           [0.627],
           [0.627],
           [0.627],
    ...
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.628],
           [0.631],
           [0.638],
           [0.657],
           [0.691],
           [0.742],
           [0.803],
           [0.869],
           [0.935],
           [1.   ]])

  • benchmark_f1
    ()
    float64
    0.5189

    average :

    weighted

    description :

    sklearn f1_score against the ground truth

    name :

    PhaseMapF1Score

    input_variable :

    phase_model

    output_variable :

    benchmark_f1

    input_prefix :

    None

    output_prefix :

    benchmark

    _stored_args :

    {'ground_truth': <AFL.double_agent.VirtualInstruments.ProteinGlycerolTemperaturePhaseMap object at 0x7fbc2c0f3c50>, 'bounds': {'protein': [0.5, 75.0], 'temperature': [0.5, 45.0], 'glycerol': [0.5, 10.0]}, 'model_variable': 'phase_model', 'predict': None, 'average': 'weighted', 'n_per_phase': 100, 'n_pool': 20000, 'seed': 1000, 'output_prefix': 'benchmark', 'name': 'PhaseMapF1Score'}

    array(0.519)

• Attributes: (3)

  sample_uuid :

  SAM-9bd9e417-7c07-4a54-82de-120fa519b8f1

  ag_uuid :

  AG-e508f98e-2584-46c0-9fd2-010eb4f3ccd4

  AL_campaign_name :

  manifold-95dad5a5