7.3. Migrating to 3.0

7.3.1. Summary

The newest major release of citrine-python cleans accumulated deprecations as we evolve the Citrine platform. The intent is to focus users as we aim to reduce confusion by providing a single way to accomplish each of your tasks.

Keep in mind that you can keep using 2.x until you’re ready to upgrade. But until you do, you won’t get any new features or bug fixes.

7.3.1.1. Goals

The intent of this guide is not to itemize every piece of code removed. The easiest way to determine what you’ll need to change is to upgrade citrine to the latest 2.x release (2.42.2), run your scripts, and take note of the deprecation warnings. Whenever possible, those warnings will direct you on how to modify your code such that it will continue to function as desired upon upgrading to citrine-python 3.x.

This guide seeks to give a high-level overview of those changes, naming some of the categories of elements no longer supported and what action to take, as well as some of the more consequential individual changes.

7.3.2. Versions / Runtimes

The following library versions and Python versions are no longer supported.

7.3.2.1. Versions < 2.26.1

The citrine-python SDK is a client for the Citrine platform. As such, we will occasionally need to make upgrades to the platform which will break old versions of the SDK.

At some point after the release of 3.0, we will be making platform upgrades which will change the way clients must interact with Search Spaces. So if you’re using any version of citrine prior to 2.26.1 (released on June 28, 2023), and you’re interacting with Search Spaces (e.g. through project.design_spaces), your code will break. Please upgrade to the latest 2.x release, or to 3.0, to avoid this issue. If this poses any problems for you, please notify your customer contact so we can work with you.

7.3.2.2. Python 3.7

Official upstream support for Python 3.7 by the Python Software Foundation ended in June 2023. As such, we no longer support its use, and may begin using language features which are not backwards compatable with it. Upgrade to at least Python 3.8, keeping in mind their migration guide.

7.3.3. Features

The following features are no longer supported.

7.3.3.1. Branch ID

Previously, branch references were inconsistent. Some used a unique “branch ID”, and others the “root ID”. This was further complicated by the web app only ever showing the “root ID”. The reason has to do with the platform implementation, but resulted in a confusing user experience.

Beginning in 3.0, that “branch ID” is hidden from users. Instead, the SDK will always present the branch’s root ID and version, akin to Predictor ID and version. To access branches, you’ll just use that root ID, and optionally the version: omitting the version will grab the most recent version, which will almost always be what you want.

7.3.3.2. status_info

We have completed moving all our assets which previously used status_info (such as but not limited to Predictor and DesignWorkflow) to use status_detail. These objects contain richer information, such as log level and (optionally) error codes, along with the message.

7.3.3.3. DesignSpace.archive and DesignSpace.restore

In the past, archiving a Search Space required updating it, which carried the risk of accidental modification. Since 2.26.1, we’ve supported a separate archive() and restore() call. So we no longer support archiving via update().

7.3.3.4. citrine.builders

This package contained a handful of utilities which were by all accounts unused, and better suited to live outside citrine-python, anyways.

7.3.3.5. formulation_descriptor parameters

In many cases, the Citrine platform will generate an appropriate formulation descriptor on your behalf. For example, when creating a SimpleMixturePredictor or GemTableDataSource. In such cases, you can no longer specify a formulation descriptor.

7.3.3.6. `project.modules`

This was the remnant of the old Citrine platform, before we began to specialize our assets. For over a year, it has only returned Search Spaces, for which you should be using project.design_spaces. As such, both it and citrine.resources.modules were dropped.

7.3.3.7. Dehydrated Search Spaces

This is a feature from the early days of the platform. It hasn’t been supported for quite some time due to lack of use and complexity of support. But mechanisms for it were still present in citrine-python, allowing users to specify subspaces by ID. Fully dropping support completes its removal.

7.3.3.8. Process File Protocol

This refers to the old method of getting data on the platform using Dataset.files.process. It’s been supplanted by ingest(), rendering process and the whole citrine.resources.job module irrelevant.

7.3.3.9. convert_to_graph and convert_and_update

SimpleMLPredictor was a very old type of AI Model which hasn’t been supported by the platform in a long time. As such, these methods to convert them into the equivalent GraphPredictor are no longer needed. If you think you still use a SimpleMLPredictor, please reach out to your customer contact so we can work with you to convert it.

7.3.3.10. `find_or_create_project()` requires a team ID

In mid-2022, the platform introduced teams, which are collections of projects. As such, starting with 3.0, find_or_create_project() can only operate on a ProjectCollection which includes a team ID. That is, instead of passing citrine.projects, you most likely want to pass team.projects.

7.3.3.11. Ingredient Ratio Constraint bases are now sets

They were initially implemented as Python dictionaries to allow for flexibility. But as we evolved their usage on the platform, we found we only needed the list of ingredients/labels. To allow migration while preserving the old behavior, we added basis_ingredient_names() and basis_label_names(). Note that once you’ve upgraded to 3.0, you’ll be prompted to move back to basis_ingredients() and basis_labels().