basic_functionality.rst

Managing Resources

The Citrine Python client can create, read, update, and delete resources. This document describes those mechanics in general terms, without assuming a knowledge of what the resources are.

In general, for every resource type there is a corresponding collection. For example, a :class:`~citrine.resources.project.ProjectCollection` contains :class:`Projects <citrine.resources.project.Project>`. Generally, the collection is used to perform create/read/update/delete actions on the resources. This pattern is illustrated in the examples below.

Creating

To create a local resource, initialize it as you would any other Python object. For example,

from gemd import ProcessSpec
buy_electrolyte_spec = ProcessSpec("Buy ammonium chloride")

creates a process spec with the display name "Buy ammonium chloride" and no other information.

To persist a resource in the database, you must upload it using the register command of the relevant collection. Assume there is a dataset battery_dataset_1. This dataset has an attribute .process_specs, which produces a :class:`~citrine.resources.process_spec.ProcessSpecCollection`. The collection has a register command, which registers the :class:`~citrine.resources.process_spec.ProcessSpec`, like so:

battery_dataset_1.process_specs.register(buy_electrolyte_spec)

If you tried to register the process spec to the dataset's material run collection, using battery_dataset_1.material_runs.register(buy_electrolyte_spec), then an error would result since the types don't match.

The register command returns a copy of the resource as it now exists in the database. The database may decorate the object with additional information, such as a unique identifier string that you can use to retrieve it in the future.

Controlling Flow

It is often useful to know when a resource has completed validating, especially when subsequent lines of code involve the validated resource. The wait_while_validating function will pause execution of the script until the resource has successfully validated.

sintering_model = sintering_project.predictors.register(sintering_model)
wait_while_validating(collection=sintering_project.predictors, module=sintering_model)

Similarly, the wait_while_executing function will wait for a design or performance evaluation workflow to complete executing.

pew_workflow = sintering_project.predictor_evaluation_workflows.register(pew_workflow)
pew_workflow = wait_while_validating(collection=sintering_project.predictor_evaluation_workflows, module=pew_workflow)
pew_ex = pew_workflow.trigger(sintering_model)
wait_while_executing(collection=sintering_project.predictor_evaluation_executions, execution=pew_ex, print_status_info=True)

Checking Status

After registering an asset, the status command can be used to obtain a static readout of the state of the asset on the platform (e.g., VALID, INVALID, VALIDATING, SUCCEEDED, FAILED, INPROGRESS).

sintering_model = sintering_project.predictors.register(sintering_model)
sintering_model.status

The status_info command returns additional details about an asset's status that can be very useful for debugging.

sintering_model.status_info

Reading

There are several ways to retrieve a resource from the database.

Get

Get retrieves a specific resource with a known unique identifier string. If the team ceramic_resistors_team has a dataset with an id that you have saved as special_dataset_id, then you could retrieve it with:

ceramic_resistors_team.datasets.get(special_dataset_id)

List

List returns an iterator of every resource in a collection. To list every design space in the project uv_absorbing_glasses, use the command:

uv_absorbing_glasses.design_spaces.list()

Updating

The update command updates an object. The following code creates and persists a process spec sintering to a dataset tungsten_dataset, then updates it locally and persists that update.

sintering = tungsten_dataset.register(ProcessSpec(name="Sinter a powder"))
sintering.notes = "Forgot to add notes!"
tungsten_dataset.update(sintering)

Deleting

Resources can generally be deleted with the delete command. However, resources may link to other resources, and deleting these interconnected objects is tricky. For more information, see the section on :ref:`deleting data objects <deleting_data_objects_label>`.

AI modules cannot be deleted at this time, but they can be :ref:`archived <archiving_label>`.

Data Model Object Specific Methods

The client supports additional methods on certain data model object resources, such as more powerful ways to get resources. These are detailed in the documentation of :doc:`GEMD data objects <../data_entry>`