Models Client Examples

The ModelsClient class encapsulates interactions with trained models on Citrination.


The .predict() method allows you to make a prediction with a model by referencing the ID of a Data View.

The predict method takes a list of candidates, each of which is a dictionary of the inputs required for that data view. You may also specify the prediction method (either from_distribution or scalar).

# ... client initialization left out

models_client = client.models

# The input to this data view is a SMILES string
inputs = [
  {"formula": "NaCl", "Property Crystallinity": "Amorphous"},
  {"formula": "MgO2", "Property Crystallinity": "Polycrystalline"}

data_view_id = "4106"

# This prediction will return a list of two PredictionResult objects since
# there were two candidates passed in as inputs.
prediction_results = models_client.predict(data_view_id, inputs, method="scalar")

# Retrieve the prediction value and loss for the "Property Band gap" output
# for the NaCl candidate
nacl_result = prediction_results[0]
nacl_value = nacl_result.get_value("Property Band gap").value
nacl_loss = nacl_result.get_value("Property Band gap").loss


You can retrieve the t-SNE analysis for a model by calling the .tsne() method with the ID of a data view with trained models.

The result of this call will be a Tsne instance which contains projections for each of the the outputs for the models trained on the data view.

# ... client initialization left out

models_client = client.models

data_view_id = "4106"

resp = models_client.tsne(data_view_id)

band_gap_projection = resp.get_projection('Property Band gap')
band_gap_projection.xs # returns the x component of the TSNE projection
band_gap_projection.ys # returns the y component of the TSNE projection
band_gap_projection.responses # returns the responses for the points in the projection
band_gap_projection.uids # returns the record UIDs for the projection
band_gap_projection.tags # returns the tags on the points in the projection


The .submit_design_run() method allows you to start a design run.

# ... client initialization left out

linear_design = models_client.submit_design_run(data_view_id=data_view_id, num_candidates=10,
                                                target=Target('Property Bulk modulus', .1), constraints=[],
# Wait for the design to finish
print("DesignUUID: " + linear_design.uuid)
while True:
    design_status = models_client.get_design_run_status(data_view_id, linear_design.uuid)
    if design_status.status == 'Finished':

results = models_client.get_design_run_results(data_view_id, linear_design.uuid)
# [{'descriptor_values': {'formula': 'Ba', 'Property Bulk modulus': '9.0', ...