QCPortal Clients

pretty_print_request(req)

Parameters:

req (PreparedRequest)

Return type:

None

pretty_print_response(res)

Parameters:

res (Response)

Return type:

None

exception PortalRequestError

Bases: Exception

__init__(msg, status_code, details)

Parameters:

• msg (str)

• status_code (int)

• details (dict[str, Any])

Return type:

None

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class PortalClientBase

Bases: object

__init__(address, username=None, password=None, verify=True, show_motd=True, *, api_token=None, information_endpoint='api/v1/information')

Initializes a PortalClient instance from an address and verification information.

Parameters:

• address (str) – The IP and port of the FractalServer instance (“192.168.1.1:8888”)

• username (str | None) – The username to authenticate with.

• password (str | None) – The password to authenticate with.

• verify (bool) – Verifies the SSL connection with a third party server. This may be False if a FractalServer was not provided a SSL certificate and defaults back to self-signed SSL keys.

• show_motd (bool) – If a Message-of-the-Day is available, display it

• api_token (str | None) – A long-lived API token to authenticate with, as an alternative to a username and password. Mutually exclusive with them. Unlike the username/password flow, this needs no token refreshing, so it is suitable for clients that only set a static header.

• information_endpoint (str)

Return type:

None

username: str | None

user_id: int | None

server_info: dict[str, Any]

classmethod from_file(server_name=None, config_path=None)

Creates a new client given information in a file.

If no path is passed in, the current working directory and finally ~/.qca are searched for “qcportal_config.yaml”

Parameters:

• server_name (str | None) – Name/alias of the server in the yaml file

• config_path (str | None) – Full path to a configuration file, or a directory containing “qcportal_config.yaml”.

Returns:

A new client, constructed with the settings found in the file

Return type:

_ClientType

classmethod from_env()

Creates a new client given information stored in environment variables

The environment variables are:

• QCPORTAL_ADDRESS (required)

• QCPORTAL_USERNAME (optional)

• QCPORTAL_PASSWORD (optional)

• QCPORTAL_API_TOKEN (optional, mutually exclusive with username/password)

• QCPORTAL_VERIFY (optional, defaults to True)

• QCPORTAL_CACHE_DIR (optional)

Returns:

A new client, constructed with the settings found in the environment

Return type:

_ClientType

property encoding: str

make_request(method: str, endpoint: str, response_model: type[_V], *, body_model: Any = None, url_params_model: Any = None, body: Any = None, url_params: Any = None, upload_files: Iterable[tuple[str, str]] | None = None, allow_retries: bool = True, additional_headers: dict[str, Any] | None = None) → _V

make_request(method: str, endpoint: str, response_model: None, *, body_model: Any = None, url_params_model: Any = None, body: Any = None, url_params: Any = None, upload_files: Iterable[tuple[str, str]] | None = None, allow_retries: bool = True, additional_headers: dict[str, Any] | None = None) → None

make_request(method: str, endpoint: str, response_model: Any, *, body_model: Any = None, url_params_model: Any = None, body: Any = None, url_params: Any = None, upload_files: Iterable[tuple[str, str]] | None = None, allow_retries: bool = True, additional_headers: dict[str, Any] | None = None) → Any

Parameters:

• method (str)

• endpoint (str)

• response_model (Any)

• body_model (Any)

• url_params_model (Any)

• body (Any)

• url_params (Any)

• upload_files (Iterable[tuple[str, str]] | None)

• allow_retries (bool)

• additional_headers (dict[str, Any] | None)

Return type:

Any

download_file(endpoint, destination_path, overwrite=False, expected_size=None, show_progress=False)

Download a file with optional progress bar

Parameters:

• endpoint (str) – API endpoint to download from

• destination_path (str) – Where to save the file

• overwrite (bool) – Whether to overwrite existing files

• expected_size (int | None) – Expected size of the file in bytes (used for progress bar if enabled)

• show_progress (bool) – Whether to show a progress bar during download

Returns:

A tuple of the size of the downloaded file (in bytes) and its sha256 checksum

Return type:

tuple[int, str]

ping()

Pings the server to see if it is up

Returns:

True if the server is up and responded to the ping. False otherwise

Return type:

bool

get_server_information()

Request general information about the server

Returns:

Server information.

Return type:

dict[str, Any]

class PortalClient

Bases: PortalClientBase

Main class for interacting with a QCArchive server

__init__(address, username=None, password=None, verify=True, show_motd=True, *, api_token=None, cache_dir=None, cache_max_size=0)

Parameters:

• address (str) – The host or IP address of the FractalServer instance, including protocol and port if necessary (”https://ml.qcarchive.molssi.org”, “http://192.168.1.10:8888”)

• username (str | None) – The username to authenticate with.

• password (str | None) – The password to authenticate with.

• verify (bool) – Verifies the SSL connection with a third party server. This may be False if a FractalServer was not provided an SSL certificate and defaults back to self-signed SSL keys.

• show_motd (bool) – If a Message-of-the-Day is available, display it

• api_token (str | None) – A long-lived API token to authenticate with, instead of a username and password

• cache_dir (str | None) – Directory to store an internal cache of records and other data

• cache_max_size (int) – Maximum size of the cache directory

Return type:

None

get_server_information()

Request general information about the server

Returns:

Server information.

Return type:

dict[str, Any]

get_server_openapi_spec()

Request the OpenAPI specification for the server

Returns:

OpenAPI specification.

Return type:

dict[str, Any]

get_server_stats()

Request statistics about the server

Returns:

Server statistics.

Return type:

list[ServerStatsEntry]

get_motd()

Gets the Message-of-the-Day (MOTD) from the server

Returns:

The current Message-of-the-Day. May be an empty string if none is set

Return type:

str

set_motd(new_motd)

Sets the Message-of-the-Day (MOTD) on the server

Parameters:

new_motd (str) – The new Message-of-the-Day. Set to an empty string to remove the existing one

Return type:

None

add_project(name, description=None, tagline=None, tags=None, default_compute_tag='*', default_compute_priority=PriorityEnum.normal, extras=None, existing_ok=False)

Creates a new project on the server

Project names are unique across the server, and are compared case-insensitively.

Parameters:

• name (str) – Name of the new project

• description (str | None) – Optional longer description of the project

• tagline (str | None) – Optional short description of the project

• tags (list[str] | None) – Optional list of tags to attach to the project

• default_compute_tag (str) – The default compute tag for computations created within this project. Records and datasets added to the project inherit this unless they override it

• default_compute_priority (PriorityEnum) – The default priority for computations created within this project

• extras (dict[str, Any] | None) – Optional dictionary of arbitrary additional information

• existing_ok (bool) – If True, return the existing project if one already exists with this name, rather than raising an exception

Returns:

The new project (or existing project if existing_ok=True and a project with the given name already exists)

Return type:

Project

get_project(project_name_or_id)

Obtain a project by name

The name is matched case-insensitively.

Parameters:

project_name_or_id (str | int) – Name or ID of the project. Integers will always be treated as IDs, and strings will always be treated as names.

Returns:

The project with the given name

Return type:

Project

get_project_by_id(project_id)

Obtain a project by ID

Parameters:

project_id (int) – ID of the project to obtain

Returns:

The project with the given ID

Return type:

Project

delete_project(project_id, delete_records=False, delete_datasets=False, delete_dataset_records=False)

Deletes a project from the server

By default, only the project itself is deleted. The records and datasets it contained remain on the server.

Parameters:

• project_id (int) – ID of the project to delete

• delete_records (bool) – If True, also delete the records that were added directly to the project

• delete_datasets (bool) – If True, also delete the datasets that were in the project

• delete_dataset_records (bool) – If True, also delete the records contained in those datasets

Return type:

None

list_projects()

Obtain a summary of all projects on the server

Each entry is a dictionary with the keys id, project_name, tagline, tags, description, record_count, dataset_count, owner_user, and creator_user.

The full project is not returned - use get_project() or get_project_by_id() for that.

Returns:

A list of dictionaries, one per project, ordered by project ID

Return type:

list[dict[str, Any]]

query_project_records(record_id)

Determine which projects the given records belong to

Records that are not in any project simply do not appear in the result, so the returned list may be shorter than the list of IDs given.

Parameters:

record_id (int | Iterable[int]) – A record ID, or a collection of record IDs, to look up

Returns:

A list of dictionaries, each with the keys record_id, project_id, project_name, and record_name

Return type:

list[dict[str, Any]]

query_project_datasets(dataset_id)

Determine which projects the given datasets belong to

Datasets that are not in any project simply do not appear in the result, so the returned list may be shorter than the list of IDs given.

Parameters:

dataset_id (int | Iterable[int]) – A dataset ID or list of dataset IDs to look up

Returns:

A list of dictionaries, each with the keys dataset_id, project_id, project_name, and dataset_name

Return type:

list[dict[str, Any]]

list_datasets()

Obtain a summary of all datasets on the server

Returns:

A list of dictionaries, one per dataset, containing basic information about each dataset

Return type:

list[dict[str, Any]]

list_datasets_table()

Formats a summary of all datasets on the server as a table

Returns:

A table of the datasets on the server (id, type, record count, and name), as a string suitable for printing

Return type:

str

print_datasets_table()

Prints a summary of all datasets on the server as a table

Return type:

None

get_dataset(dataset_type, dataset_name)

Obtain a dataset with the specified type and name

Parameters:

• dataset_type (str) – Type of the dataset to obtain (“singlepoint”, “optimization”, …)

• dataset_name (str) – Name of the dataset to obtain. The name is matched case-insensitively

Returns:

The dataset, as a subclass of BaseDataset matching the type of the dataset

Return type:

BaseDataset

query_dataset_records(record_id, dataset_type=None)

Determine which datasets the given records belong to

Parameters:

• record_id (int | Iterable[int]) – A record ID, or a collection of record IDs, to look up

• dataset_type (Iterable[str] | None) – Only include datasets of these types in the result. If None, all types are included

Returns:

A list of dictionaries, each with information about the dataset a record belongs to

Return type:

list[dict[str, Any]]

get_dataset_by_id(dataset_id)

Obtain a dataset with the specified ID

Parameters:

dataset_id (int) – ID of the dataset to obtain

Returns:

The dataset, as a subclass of BaseDataset matching the type of the dataset

Return type:

BaseDataset

dataset_from_cache(file_path)

Obtain a dataset from a local cache file

The cache file must have been created while connected to the same server this client is connected to. If the dataset no longer exists on the server, the cache is marked read-only and the dataset can still be used offline.

Parameters:

file_path (str) – Full path to an existing dataset cache file (see create_dataset_view())

Returns:

The dataset stored in the cache file, attached to this client

Return type:

BaseDataset

create_dataset_view(dataset_id, file_path, include=None, overwrite=False)

Downloads a dataset into a file that can be used offline

The entire dataset (entries, specifications, and records) is downloaded, which may take a while for large datasets. The resulting file can be opened with load_dataset_view() or dataset_from_cache().

Parameters:

• dataset_id (int) – ID of the dataset to download

• file_path (str) – Full path to the file to create (including filename)

• include (Iterable[str] | None) – Additional fields to include in the downloaded records

• overwrite (bool) – If True, allow for overwriting an existing file. If False, and a file already exists at the given path, an exception is raised

Return type:

None

get_dataset_status_by_id(dataset_id)

Obtain the status of the records in a dataset

Parameters:

dataset_id (int) – ID of the dataset to obtain the status of

Returns:

A dictionary of specification name to a dictionary of record status to the number of records of the dataset with that status

Return type:

dict[str, dict[RecordStatusEnum, int]]

add_dataset(dataset_type, name, description=None, tagline=None, tags=None, group=None, provenance=None, visibility=None, default_compute_tag='*', default_compute_priority=PriorityEnum.normal, extras=None, owner_group=None, existing_ok=False, **kwargs)

Adds a new dataset to the server

Dataset names are unique for a given dataset type, and are compared case-insensitively.

Parameters:

• dataset_type (str) – Type of the dataset to create (“singlepoint”, “optimization”, …)

• name (str) – Name of the new dataset

• description (str | None) – Optional longer description of the dataset

• tagline (str | None) – Optional short description of the dataset

• tags (list[str] | None) – Optional list of tags to attach to the dataset

• group (str | None) – Deprecated and unused

• provenance (dict[str, Any] | None) – Optional dictionary describing where this dataset came from

• visibility (bool | None) – Deprecated and unused

• default_compute_tag (str) – The default compute tag for computations submitted from this dataset

• default_compute_priority (PriorityEnum) – The default priority for computations submitted from this dataset

• extras (dict[str, Any] | None) – Optional dictionary of arbitrary additional information

• owner_group (str | None) – Deprecated and unused

• existing_ok (bool) – If True, return the existing dataset if one already exists with this type and name, rather than raising an exception

• kwargs (Any)

Returns:

The new dataset (or the existing dataset if existing_ok=True and one with the given type and name already exists)

Return type:

BaseDataset

delete_dataset(dataset_id, delete_records)

Deletes a dataset from the server

Parameters:

• dataset_id (int) – ID of the dataset to delete

• delete_records (bool) – If True, also delete the records the dataset contains. Otherwise the records remain on the server, just not as part of a dataset

Return type:

None

clone_dataset(source_dataset_id, new_dataset_name)

Creates a copy of an existing dataset

The new dataset has the same entries, specifications, and records as the source dataset. The records themselves are not duplicated - both datasets refer to the same records.

Parameters:

• source_dataset_id (int) – ID of the dataset to copy

• new_dataset_name (str) – Name to give the new dataset

Returns:

The newly-created dataset

Return type:

BaseDataset

get_external_file_direct_link(file_id)

Obtain a URL for downloading an external file directly

Depending on how the server stores the file, this may be a link to another service (cloud storage, for example) rather than to the server itself.

Parameters:

file_id (int) – ID of the file to obtain a link for

Returns:

A URL the file can be downloaded from

Return type:

str

download_external_file(file_id, destination_path, overwrite=False)

Downloads an external file to the given path

The file size and checksum will be checked against the metadata stored on the server

Parameters:

• file_id (int) – ID of the file to obtain

• destination_path (str) – Full path to the destination file (including filename)

• overwrite (bool) – If True, allow for overwriting an existing file. If False, and a file already exists at the given destination path, an exception will be raised.

Returns:

A tuple of file size and sha256 checksum.

Return type:

tuple[int, str]

get_molecules(molecule_ids: int, missing_ok: Literal[False] = False) → Molecule

get_molecules(molecule_ids: int, missing_ok: bool) → Molecule | None

get_molecules(molecule_ids: Collection[int], missing_ok: Literal[False] = False) → list[Molecule]

get_molecules(molecule_ids: Collection[int], missing_ok: bool) → list[Molecule | None]

Obtains molecules with the specified IDs from the server

Parameters:

• molecule_ids (int | Collection[int]) – A single molecule ID, or a collection of molecule IDs (list, tuple, set, numpy array, …)

• missing_ok (bool) – If set to True, then missing molecules will be tolerated, and the returned list of Molecules will contain None for the corresponding IDs that were not found.

Returns:

Molecules, in the same order as the requested ids. If given a collection of ids, the return value will be a list. Otherwise, it will be a single Molecule. Note that if the ids are given as an unordered collection (a set, for example), the order of the results is however that collection itself iterates.

Return type:

Molecule | list[Molecule] | list[Molecule | None] | None

query_molecules(*, molecule_hash=None, molecular_formula=None, identifiers=None, limit=None)

Query molecules by attributes.

Do not rely on the returned molecules being in any particular order.

Parameters:

• molecule_hash (str | Iterable[str] | None) – Queries molecules by hash

• molecular_formula (str | Iterable[str] | None) – Queries molecules by molecular formula. Molecular formulas are not order-sensitive (e.g. “H2O == OH2 != Oh2”).

• identifiers (dict[str, str | Iterable[str]] | None) – Additional identifiers to search for (smiles, etc)

• limit (int | None) – The maximum number of Molecules to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

MoleculeQueryIterator

add_molecules(molecules)

Add molecules to the server database

If the same molecule (defined by having the same hash) already exists, then the existing molecule is kept and that particular molecule is not added.

Parameters:

molecules (Sequence[Molecule]) – A list of Molecules to add to the server.

Returns:

Metadata about what was inserted, and a list of IDs of the molecules in the same order as the molecules parameter.

Return type:

tuple[InsertMetadata, list[int]]

upload_molecules(file_paths)

Adds molecules to the server by uploading files containing them

A file may contain more than one molecule, and archives (zip, tar, tar.gz, …) of such files may be uploaded as well. The file type is determined from the file extension.

As with add_molecules(), molecules that already exist on the server are not added again - the existing molecule id is returned instead.

Parameters:

file_paths (Sequence[str]) – Full paths of the files to upload

Returns:

A tuple of results and errors. The results map each uploaded file name to a list of the molecules obtained from it, as (name of the molecule within the file, molecule id) pairs. The errors are descriptions of any files (or molecules within a file) that could not be processed

Return type:

tuple[dict[str, list[tuple[str, int]]], list[str]]

modify_molecule(molecule_id, name=None, comment=None, identifiers=None, overwrite_identifiers=False)

Modify molecules on the server

This is only capable of updating the name, comment, and identifiers fields (except molecule_hash and molecular formula).

If a molecule with that id does not exist, an exception is raised

Parameters:

• molecule_id (int) – ID of the molecule to modify

• name (str | None) – New name for the molecule. If None, name is not changed.

• comment (str | None) – New comment for the molecule. If None, comment is not changed

• identifiers (dict[str, Any] | Identifiers | None) – A new set of identifiers for the molecule

• overwrite_identifiers (bool) – If True, the identifiers of the molecule are set to be those given exactly (ie, identifiers that exist in the DB but not in the new set will be removed). Otherwise, the new set of identifiers is merged into the existing ones. Note that molecule_hash and molecular_formula are never removed.

Returns:

Metadata about the modification/update.

Return type:

UpdateMetadata

delete_molecules(molecule_ids)

Deletes molecules from the server

This will not delete any molecules that are in use

Parameters:

molecule_ids (int | Collection[int]) – A single molecule ID, or a collection of molecule IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about what was deleted. The indices it contains refer to positions in the molecule ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

DeleteMetadata

get_records(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → BaseRecord

get_records(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → BaseRecord | None

get_records(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[BaseRecord]

get_records(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[BaseRecord | None]

Obtain records of all types with specified IDs

This function will return record objects of the given ID no matter what the type is. All records are unique by ID (ie, an optimization will never have the same ID as a singlepoint).

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

BaseRecord | list[BaseRecord] | list[BaseRecord | None] | None

query_records(*, record_id=None, record_type=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, creator_user=None, limit=None, include=None)

Query records of all types based on common fields

This is a general query of all record types, so it can only filter by fields that are common among all records.

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• record_type (str | Iterable[str] | None) – Query records whose type is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list (usernames or IDs)

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[BaseRecord]

reset_records(record_ids)

Resets running or errored records to be waiting again

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

cancel_records(record_ids)

Marks running, waiting, or errored records as cancelled

A cancelled record will not be picked up by a manager.

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

invalidate_records(record_ids)

Marks a completed record as invalid

An invalid record is one that supposedly successfully completed. However, after review, is not correct.

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

delete_records(record_ids, soft_delete=True, delete_children=True)

Delete records from the database

If soft_delete is True, then the record is just marked as deleted and actually deletion may happen later. Soft delete can be undone with undelete

Parameters:

• record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

• soft_delete (bool) – Don’t actually delete the record, just mark it for later deletion

• delete_children (bool) – If True, attempt to delete child records as well

Returns:

Metadata about what was deleted. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

DeleteMetadata

uninvalidate_records(record_ids)

Undo the invalidation of records

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

uncancel_records(record_ids)

Undo the cancellation of records

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

undelete_records(record_ids)

Undo the (soft) deletion of records

Parameters:

record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

modify_records(record_ids, new_compute_tag=None, new_compute_priority=None, **kwargs)

Modify the compute tag or compute priority of a record

Parameters:

• record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

• new_compute_tag (str | None) – The new compute tag for the records. If None, the tag is not changed

• new_compute_priority (PriorityEnum | None) – The new compute priority for the records. If None, the priority is not changed

• kwargs (Any)

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

add_comment(record_ids, comment)

Adds a comment to records

Parameters:

• record_ids (int | Collection[int]) – A single record ID, or a collection of record IDs (list, tuple, set, numpy array, …)

• comment (str) – The comment string to add. Your username will be added automatically

Returns:

Metadata about which records were updated. The indices it contains refer to positions in the record ids given - if those were given as an unordered collection (a set, for example), those positions follow however that collection iterates.

Return type:

UpdateMetadata

get_waiting_reason(record_id)

Get the reason a record is in the waiting status

The return is a dictionary, with a ‘reason’ key containing the overall reason the record is waiting. If appropriate, there is a ‘details’ key that contains information for each active compute manager on why that manager is not able to pick up the record’s task.

Parameters:

record_id (int) – The record ID to test

Returns:

A dictionary containing information about why the record is not being picked up by compute managers

Return type:

dict[str, Any]

add_singlepoints(molecules, program, driver, method, basis, keywords=None, protocols=None, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new singlepoint computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per molecule.

Parameters:

• molecules (int | Molecule | Sequence[int | Molecule]) – The Molecules or Molecule ids to compute with the above methods

• program (str) – The computational program to execute the result with (e.g., “rdkit”, “psi4”).

• driver (SinglepointDriver) – The primary result that the compute will acquire {“energy”, “gradient”, “hessian”, “properties”}

• method (str) – The computational method to use (e.g., “B3LYP”, “PBE”)

• basis (str | None) – The basis to apply to the computation (e.g., “cc-pVDZ”, “6-31G”)

• keywords (dict[str, Any] | None) – The program-specific keywords for the computation

• protocols (SinglepointProtocols | dict[str, Any] | None) – Protocols for storing more/less data for each computation

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

tuple[InsertMetadata, list[int]]

get_singlepoints(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → SinglepointRecord

get_singlepoints(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → SinglepointRecord | None

get_singlepoints(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[SinglepointRecord]

get_singlepoints(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[SinglepointRecord | None]

Obtain singlepoint records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

SinglepointRecord | list[SinglepointRecord] | list[SinglepointRecord | None] | None

query_singlepoints(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, driver=None, method=None, basis=None, keywords=None, molecule_id=None, creator_user=None, limit=None, include=None)

Queries singlepoint records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose program is in the given list

• driver (SinglepointDriver | Iterable[SinglepointDriver] | None) – Query records whose driver is in the given list

• method (str | Iterable[str] | None) – Query records whose method is in the given list

• basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

• keywords (dict[str, Any] | Iterable[dict[str, Any]] | None) – Query records with these keywords (exact match)

• molecule_id (int | Iterable[int] | None) – Query records whose molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[SinglepointRecord]

add_optimizations(initial_molecules, program, qc_specification, keywords=None, protocols=None, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new geometry optimization calculations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule.

Parameters:

• initial_molecules (int | Molecule | Sequence[int | Molecule]) – Initial molecule/geometry to optimize

• program (str) – Which program to use for the optimization (ie, geometric)

• qc_specification (QCSpecification) – The method, basis, etc, to optimize the geometry with

• keywords (dict[str, Any] | None) – Program-specific keywords for the optimization program (not the qc program)

• protocols (OptimizationProtocols | None) – Protocols for storing more/less data for each computation (for the optimization)

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

tuple[InsertMetadata, list[int]]

get_optimizations(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → OptimizationRecord

get_optimizations(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → OptimizationRecord | None

get_optimizations(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[OptimizationRecord]

get_optimizations(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[OptimizationRecord | None]

Obtain optimization records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

OptimizationRecord | list[OptimizationRecord] | list[OptimizationRecord | None] | None

query_optimizations(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, final_molecule_id=None, creator_user=None, limit=None, include=None)

Queries optimization records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (singlepoint calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

• qc_basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

• initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

• final_molecule_id (int | Iterable[int] | None) – Query records whose final molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[OptimizationRecord]

add_torsiondrives(initial_molecules, program, optimization_specification, keywords, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new torsiondrive computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per set of molecules

Parameters:

• initial_molecules (Sequence[Sequence[int | Molecule]]) – Molecules to start the torsiondrives. Each torsiondrive can start with multiple molecules, so this is a nested list

• program (str) – The program to run the torsiondrive computation with (“torsiondrive”)

• optimization_specification (OptimizationSpecification) – Specification of how each optimization of the torsiondrive should be run

• keywords (TorsiondriveKeywords | dict[str, Any]) – The torsiondrive keywords for the computation

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

tuple[InsertMetadata, list[int]]

get_torsiondrives(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → TorsiondriveRecord

get_torsiondrives(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → TorsiondriveRecord | None

get_torsiondrives(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[TorsiondriveRecord]

get_torsiondrives(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[TorsiondriveRecord | None]

Obtain torsiondrive records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

TorsiondriveRecord | list[TorsiondriveRecord] | list[TorsiondriveRecord | None] | None

query_torsiondrives(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, creator_user=None, limit=None, include=None)

Queries torsiondrive records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose torsiondrive program is in the given list

• optimization_program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

• qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

• initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[TorsiondriveRecord]

add_gridoptimizations(initial_molecules, program, optimization_specification, keywords, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new gridoptimization computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule

Parameters:

• initial_molecules (int | Molecule | Sequence[int | Molecule]) –

  Molecules to start the gridoptimizations. Each gridoptimization starts with

  a single molecule.

• program (str) – The program to run the gridoptimization computation with (“gridoptimization”)

• optimization_specification (OptimizationSpecification) – Specification of how each optimization of the gridoptimization should be run

• keywords (GridoptimizationKeywords | dict[str, Any]) – The gridoptimization keywords for the computation

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

tuple[InsertMetadata, list[int]]

get_gridoptimizations(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → GridoptimizationRecord

get_gridoptimizations(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → GridoptimizationRecord | None

get_gridoptimizations(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[GridoptimizationRecord]

get_gridoptimizations(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[GridoptimizationRecord | None]

Obtain gridoptimization records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

GridoptimizationRecord | list[GridoptimizationRecord] | list[GridoptimizationRecord | None] | None

query_gridoptimizations(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, creator_user=None, limit=None, include=None)

Queries gridoptimization records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (optimization calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose gridoptimization program is in the given list

• optimization_program (str | Iterable[str] | None) – Query records whose optimization program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

• qc_basis (str | Iterable[str | None] | None) – Query records whose basis is in the given list

• initial_molecule_id (int | Iterable[int] | None) – Query records whose initial molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[GridoptimizationRecord]

add_reactions(stoichiometries, program, singlepoint_specification, optimization_specification, keywords, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new reaction computations to the server

Reactions can have a singlepoint specification, optimization specification, or both; at least one must be specified. If both are specified, an optimization is done, followed by a singlepoint computation. Otherwise, only the specification that is specified is used.

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per reaction

Parameters:

• stoichiometries (Sequence[Sequence[tuple[float, int | Molecule]]]) – Coefficients and molecules of the reaction. Each reaction has multiple molecules/coefficients, so this is a nested list

• program (str) – The program for running the reaction computation (“reaction”)

• singlepoint_specification (QCSpecification | None) – The specification for singlepoint energy calculations

• optimization_specification (OptimizationSpecification | None) – The specification for optimization calculations

• keywords (ReactionKeywords) – The keywords for the reaction calculation/service

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input stoichiometries

Return type:

tuple[InsertMetadata, list[int]]

get_reactions(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → ReactionRecord

get_reactions(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → ReactionRecord | None

get_reactions(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[ReactionRecord]

get_reactions(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[ReactionRecord | None]

Obtain reaction records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

ReactionRecord | list[ReactionRecord] | list[ReactionRecord | None] | None

query_reactions(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, optimization_program=None, qc_program=None, qc_method=None, qc_basis=None, molecule_id=None, creator_user=None, limit=None, include=None)

Queries reaction records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (singlepoint or optimization calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose reaction program is in the given list

• optimization_program (Iterable[str | None] | None) – Query records whose optimization program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

• qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

• molecule_id (int | Iterable[int] | None) – Query reactions that contain a molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[ReactionRecord]

add_manybodys(initial_molecules, program, levels, bsse_correction, keywords, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds new manybody expansion computations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial molecule.

Parameters:

• initial_molecules (Sequence[int | Molecule]) – Initial molecules for the manybody expansion. Must have > 1 fragments.

• program (str) – The program to run the manybody computation with (“manybody”)

• levels (dict[int | Literal['supersystem'], ~qcportal.singlepoint.record_models.QCSpecification]) – Specification for the singlepoint calculations done in the expansion, keyed by the number of bodies they apply to (or “supersystem”)

• bsse_correction (BSSECorrectionEnum | Sequence[BSSECorrectionEnum]) – The basis set superposition error correction(s) to compute

• keywords (ManybodyKeywords | dict[str, Any]) – The keywords for the manybody program

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input molecules

Return type:

tuple[InsertMetadata, list[int]]

download_file(endpoint, destination_path, overwrite=False, expected_size=None, show_progress=False)

Download a file with optional progress bar

Parameters:

• endpoint (str) – API endpoint to download from

• destination_path (str) – Where to save the file

• overwrite (bool) – Whether to overwrite existing files

• expected_size (int | None) – Expected size of the file in bytes (used for progress bar if enabled)

• show_progress (bool) – Whether to show a progress bar during download

Returns:

A tuple of the size of the downloaded file (in bytes) and its sha256 checksum

Return type:

tuple[int, str]

property encoding: str

classmethod from_env()

Creates a new client given information stored in environment variables

The environment variables are:

• QCPORTAL_ADDRESS (required)

• QCPORTAL_USERNAME (optional)

• QCPORTAL_PASSWORD (optional)

• QCPORTAL_API_TOKEN (optional, mutually exclusive with username/password)

• QCPORTAL_VERIFY (optional, defaults to True)

• QCPORTAL_CACHE_DIR (optional)

Returns:

A new client, constructed with the settings found in the environment

Return type:

_ClientType

classmethod from_file(server_name=None, config_path=None)

Creates a new client given information in a file.

If no path is passed in, the current working directory and finally ~/.qca are searched for “qcportal_config.yaml”

Parameters:

• server_name (str | None) – Name/alias of the server in the yaml file

• config_path (str | None) – Full path to a configuration file, or a directory containing “qcportal_config.yaml”.

Returns:

A new client, constructed with the settings found in the file

Return type:

_ClientType

make_request(method, endpoint, response_model, *, body_model=None, url_params_model=None, body=None, url_params=None, upload_files=None, allow_retries=True, additional_headers=None)

Parameters:

• method (str)

• endpoint (str)

• response_model (Any)

• body_model (Any)

• url_params_model (Any)

• body (Any)

• url_params (Any)

• upload_files (Iterable[tuple[str, str]] | None)

• allow_retries (bool)

• additional_headers (dict[str, Any] | None)

Return type:

Any

ping()

Pings the server to see if it is up

Returns:

True if the server is up and responded to the ping. False otherwise

Return type:

bool

username: str | None

user_id: int | None

server_info: dict[str, Any]

get_manybodys(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → ManybodyRecord

get_manybodys(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → ManybodyRecord | None

get_manybodys(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[ManybodyRecord]

get_manybodys(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[ManybodyRecord | None]

Obtain manybody records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

ManybodyRecord | list[ManybodyRecord] | list[ManybodyRecord | None] | None

query_manybodys(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, initial_molecule_id=None, creator_user=None, limit=None, include=None)

Queries manybody records on the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (singlepoint calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose manybody program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose qc method is in the given list

• qc_basis (str | Iterable[str] | None) – Query records whose qc basis is in the given list

• initial_molecule_id (int | Iterable[int] | None) – Query manybody calculations that contain an initial molecule (id) is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[ManybodyRecord]

add_nebs(initial_chains, program, singlepoint_specification, optimization_specification, keywords, compute_tag='*', compute_priority=PriorityEnum.normal, find_existing=True, **kwargs)

Adds neb calculations to the server

This checks if the calculations already exist in the database. If so, it returns the existing id, otherwise it will insert it and return the new id.

This will add one record per initial chain

Parameters:

• initial_chains (Sequence[Sequence[int | Molecule]]) – The initial chains to run the NEB calculations on. Each NEB calculation starts with a single chain (list of molecules), so this is a nested list

• program (str) – The program to run the neb computation with (“geometric”)

• singlepoint_specification (QCSpecification) – Specification of how each singlepoint (gradient/hessian) should be run

• optimization_specification (OptimizationSpecification | None) – Specification of how the transition state optimization should be run, if one was requested with the optimize_ts keyword. May be None. Note that this does not apply to the endpoint optimizations requested with the optimize_endpoints keyword, which always use geometric with the level of theory given in the singlepoint specification

• keywords (NEBKeywords | dict[str, Any]) – The NEB keywords for the computation

• compute_tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.

• compute_priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.

• find_existing (bool) – If True, search for existing records and return those. If False, always add new records

• kwargs (Any)

Returns:

Metadata about the insertion, and a list of record ids. The ids will be in the order of the input chains

Return type:

tuple[InsertMetadata, list[int]]

get_nebs(record_ids: int, missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → NEBRecord

get_nebs(record_ids: int, missing_ok: bool, *, include: Iterable[str] | None = None) → NEBRecord | None

get_nebs(record_ids: Collection[int], missing_ok: Literal[False] = False, *, include: Iterable[str] | None = None) → list[NEBRecord]

get_nebs(record_ids: Collection[int], missing_ok: bool, *, include: Iterable[str] | None = None) → list[NEBRecord | None]

Obtain NEB records with the specified IDs.

Records will be returned in the same order as the record ids. If the ids are given as an unordered collection (a set, for example), that order is however the collection itself iterates - it is up to the caller to keep track of which record is which in that case.

Parameters:

• record_ids (int | Collection[int]) – A single ID, or a collection of IDs (list, tuple, set, numpy array, …) to obtain

• missing_ok (bool) – If set to True, then missing records will be tolerated, and the returned records will contain None for the corresponding IDs that were not found.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

If a single ID was specified, returns just that record. Otherwise, returns a list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

NEBRecord | list[NEBRecord] | list[NEBRecord | None] | None

query_nebs(*, record_id=None, manager_name=None, history_manager_name=None, status=None, dataset_id=None, project_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, program=None, qc_program=None, qc_method=None, qc_basis=None, molecule_id=None, creator_user=None, limit=None, include=None)

Queries neb records from the server

Do not rely on the returned records being in any particular order.

Parameters:

• record_id (int | Iterable[int] | None) – Query records whose ID is in the given list

• manager_name (str | Iterable[str] | None) – Query records that were completed (or are currently runnning) on a manager is in the given list

• history_manager_name (str | Iterable[str] | None) – Query any records that have been run by the given manager(s), even if not currently assigned

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Query records whose status is in the given list

• dataset_id (int | Iterable[int] | None) – Query records that are part of a dataset is in the given list

• project_id (int | Iterable[int] | None) – Query records belonging to the given project IDs

• parent_id (int | Iterable[int] | None) – Query records that have a parent is in the given list

• child_id (int | Iterable[int] | None) – Query records that have a child (singlepoint or optimization calculation) is in the given list

• created_before (datetime | str | None) – Query records that were created before the given date/time

• created_after (datetime | str | None) – Query records that were created after the given date/time

• modified_before (datetime | str | None) – Query records that were modified before the given date/time

• modified_after (datetime | str | None) – Query records that were modified after the given date/time

• program (str | Iterable[str] | None) – Query records whose neb program is in the given list

• qc_program (str | Iterable[str] | None) – Query records whose qc program is in the given list

• qc_method (str | Iterable[str] | None) – Query records whose method is in the given list

• qc_basis (str | Iterable[str] | None) – Query records whose basis is in the given list

• molecule_id (int | Iterable[int] | None) – Query records whose initial chains contain a molecule (id) that is in the given list

• creator_user (int | str | Iterable[int | str] | None) – Query records created by a user in the given list

• limit (int | None) – The maximum number of records to return. Note that the server limit is always obeyed.

• include (Iterable[str] | None) – Additional fields to include in the returned record

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

RecordQueryIterator[NEBRecord]

get_managers(names: str, missing_ok: Literal[False] = False) → ComputeManager

get_managers(names: str, missing_ok: bool) → ComputeManager | None

get_managers(names: Collection[str], missing_ok: Literal[False] = False) → list[ComputeManager]

get_managers(names: Collection[str], missing_ok: bool) → list[ComputeManager | None]

Obtain manager information from the server with the specified names

Parameters:

• names (str | Collection[str]) – A single manager name, or a collection of names (list, tuple, set, …)

• missing_ok (bool) – If set to True, then missing managers will be tolerated, and the returned managers will contain None for the corresponding managers that were not found.

Returns:

If a single name was specified, returns just that manager. Otherwise, returns a list of managers, in the same order as the names given. If missing_ok was specified, None will be substituted for a manager that was not found. Note that if the names are given as an unordered collection (a set, for example), the order of the results is however that collection itself iterates.

Return type:

ComputeManager | list[ComputeManager] | list[ComputeManager | None] | None

query_managers(*, manager_id=None, name=None, cluster=None, hostname=None, status=None, modified_before=None, modified_after=None, limit=None)

Queries manager information on the server

Parameters:

• manager_id (int | Iterable[int] | None) – ID assigned to the manager (this is not the UUID. This should be used very rarely).

• name (str | Iterable[str] | None) – Queries managers whose name is in the given list

• cluster (str | Iterable[str] | None) – Queries managers whose assigned cluster is in the given list

• hostname (str | Iterable[str] | None) – Queries managers whose hostname is in the given list

• status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Queries managers whose status is in the given list

• modified_before (datetime | str | None) – Query for managers last modified before a certain time

• modified_after (datetime | str | None) – Query for managers last modified after a certain time

• limit (int | None) – The maximum number of managers to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

ManagerQueryIterator

query_active_managers(compute_tag, programs)

Queries active managers for any that can take the given compute tag or program

This will select managers that can handle any of the given compute tags, and all the given programs/versions.

Parameters:

• compute_tag (str | list[str]) – List of possible tags the task can have. A manager must have one of the tags to be considered available.

• programs (dict[str, list[str]]) – Required programs/versions for the task. A manager must have all the programs/versions to be considered available.

Returns:

List of manager names that could possible handle the given compute tags/programs.

Return type:

list[str]

query_access_log(*, module=None, method=None, before=None, after=None, user=None, limit=None)

Query the server access log

This log contains information about who accessed the server, and when.

Parameters:

• module (str | Iterable[str] | None) – Return log entries whose module is in the given list

• method (str | Iterable[str] | None) – Return log entries whose access_method is in the given list

• before (datetime | str | None) – Return log entries captured before the specified date/time

• after (datetime | str | None) – Return log entries captured after the specified date/time

• user (int | str | Iterable[int | str] | None) – User name or ID associated with the log entry

• limit (int | None) – The maximum number of log entries to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

AccessLogQueryIterator

delete_access_log(before)

Delete access log entries from the server

Parameters:

before (datetime) – Delete access log entries captured before the given date/time

Returns:

The number of access log entries deleted from the server

Return type:

int

query_error_log(*, error_id=None, user=None, before=None, after=None, limit=None)

Query the server’s internal error log

This log contains internal errors that are not always passed to the user.

Parameters:

• error_id (int | Iterable[int] | None) – Return error log entries whose id is in the list

• user (int | str | Iterable[int | str] | None) – Return error log entries whose user name or ID is in the list

• before (datetime | str | None) – Return error log entries captured before the specified date/time

• after (datetime | str | None) – Return error log entries captured after the specified date/time

• limit (int | None) – The maximum number of log entries to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

ErrorLogQueryIterator

delete_error_log(before)

Delete error log entries from the server

Parameters:

before (datetime) – Delete error log entries captured before the given date/time

Returns:

The number of error log entries deleted from the server

Return type:

int

get_internal_job(job_id)

Gets information about an internal job on the server

Parameters:

job_id (int) – ID of the internal job to obtain

Returns:

Information about the internal job, which can be used to watch its progress

Return type:

InternalJob

query_internal_jobs(*, job_id=None, name=None, user=None, runner_hostname=None, status=None, last_updated_before=None, last_updated_after=None, added_before=None, added_after=None, scheduled_before=None, scheduled_after=None, limit=None)

Queries the internal job queue on the server

Parameters:

• job_id (int | Iterable[int] | None) – ID assigned to the job

• name (str | Iterable[str] | None) – Queries jobs whose name is in the given list

• user (int | str | Iterable[int | str] | None) – User name or ID associated with the log entry

• runner_hostname (str | Iterable[str] | None) – Queries jobs that were run/are running on a given host

• status (InternalJobStatusEnum | Iterable[InternalJobStatusEnum] | None) – Queries jobs whose status is in the given list

• last_updated_before (datetime | str | None) – Query for jobs last updated before a certain time

• last_updated_after (datetime | str | None) – Query for jobs last updated after a certain time

• added_before (datetime | str | None) – Query for jobs added before a certain time

• added_after (datetime | str | None) – Query for jobs added after a certain time

• scheduled_before (datetime | str | None) – Query for jobs scheduled to run before a certain time

• scheduled_after (datetime | str | None) – Query for jobs scheduled to run after a certain time

• limit (int | None) – The maximum number of jobs to return. Note that the server limit is always obeyed.

Returns:

An iterator that can be used to retrieve the results of the query

Return type:

InternalJobQueryIterator

cancel_internal_job(job_id)

Cancels (to the best of our ability) an internal job

A job that is already running may not stop immediately, and one that has already finished is not affected.

Parameters:

job_id (int) – ID of the internal job to cancel

Return type:

None

delete_internal_job(job_id)

Removes an internal job from the server

Parameters:

job_id (int) – ID of the internal job to delete

Return type:

None

query_access_summary(*, group_by='day', before=None, after=None)

Obtains summaries of access data

This aggregate data is created on the server, so you don’t need to download all the log entries and do it yourself.

Parameters:

• group_by (str) – How to group the data. Valid options are “user”, “hour”, “day”, “country”, “subdivision”

• before (datetime | str | None) – Query for log entries with a timestamp before a specific time

• after (datetime | str | None) – Query for log entries with a timestamp after a specific time

Returns:

Aggregated access data, grouped as requested

Return type:

AccessLogSummary

list_groups()

List all user groups on the server

Returns:

Information about all the groups on the server

Return type:

list[GroupInfo]

get_group(groupname_or_id)

Get information about a group on the server

Parameters:

groupname_or_id (int | str) – The name or ID of the group to obtain

Returns:

Information about the group

Return type:

GroupInfo

add_group(group_info)

Adds a group with permissions to the server

If not successful, an exception is raised.

Parameters:

group_info (GroupInfo) – Info about the group to add. Must not contain an id

Return type:

None

delete_group(groupname_or_id)

Deletes a group on the server

Deleted groups will be removed from all users groups list

Parameters:

groupname_or_id (int | str) – The name or ID of the group to delete

Return type:

None

list_users()

List all users on the server

Returns:

Information about all the users on the server

Return type:

list[UserInfo]

get_user(username_or_id=None)

Get information about a user on the server

If the username is not supplied, then info about the currently logged-in user is obtained.

Parameters:

username_or_id (int | str | None) – The username or ID to get info about

Returns:

Information about the user

Return type:

UserInfo

add_user(user_info, password=None)

Adds a user to the server

Parameters:

• user_info (UserInfo) – Info about the user to add

• password (str | None) – The user’s password. If None, then one will be generated

Returns:

The password of the user (either the same as the supplied password, or the server-generated one)

Return type:

str

modify_user(user_info)

Modifies a user on the server

The user is determined by the id field of the input UserInfo, although the id and username are checked for consistency.

Depending on the current user’s permissions, some fields may not be updatable.

Parameters:

user_info (UserInfo) – Updated information for a user

Returns:

The updated user information as it appears on the server

Return type:

UserInfo

change_user_password(username_or_id=None, new_password=None)

Change a users password

If the username is not specified, then the current logged-in user is used.

If the password is not specified, then one is automatically generated by the server.

Parameters:

• username_or_id (int | str | None) – The name or ID of the user whose password to change. If None, then use the currently logged-in user

• new_password (str | None) – Password to change to. If None, let the server generate one.

Returns:

The new password (either the same as the supplied one, or the server generated one

Return type:

str

delete_user(username_or_id)

Delete a user from the server

Parameters:

username_or_id (int | str) – The username or ID of the user to delete

Return type:

None

list_api_tokens(username_or_id=None)

List a user’s API tokens (never including the tokens themselves)

Parameters:

username_or_id (int | str | None) – The user whose tokens to list. If None, lists the current user’s own tokens.

Return type:

list[APIToken]

create_api_token(name, expires_at=None, username_or_id=None, scope='unlimited')

Create a new API token

The returned object contains the plaintext token, which is shown only once and cannot be retrieved later.

Parameters:

• name (str) – A name to identify the token. Must be unique among the user’s tokens.

• expires_at (datetime | None) – When the token should expire (timezone-aware). If None, the server’s default policy applies (which may be no expiration).

• username_or_id (int | str | None) – The user to create the token for. If None, creates a token for the current user.

• scope (str) – What the token should be allowed to do. Currently only “unlimited” (the owner’s full role) exists; this is a placeholder for future restricted scopes.

Return type:

NewAPIToken

delete_api_token(token_id, username_or_id=None)

Delete (revoke) an API token

Parameters:

• token_id (int) – The id of the token to delete

• username_or_id (int | str | None) – The owner of the token. If None, deletes one of the current user’s own tokens.

Return type:

None

class ManagerClient

Bases: PortalClientBase

__init__(name_data, address='https://api.qcarchive.molssi.org', username=None, password=None, verify=True, show_motd=False, *, api_token=None)

Initializes a ManagerClient

Parameters:

• name_data (ManagerName) – Information about this manager’s name

• address (str) – The IP and port of the FractalServer instance (“192.168.1.1:8888”)

• username (str | None) – The username to authenticate with.

• password (str | None) – The password to authenticate with.

• verify (bool) – Verifies the SSL connection with a third party server. This may be False if a FractalServer was not provided a SSL certificate and defaults back to self-signed SSL keys.

• show_motd (bool) – If a Message-of-the-Day is available, display it

• api_token (str | None) – A long-lived API token to authenticate with, instead of a username and password

Return type:

None

activate(manager_version, programs, compute_tags)

Registers/Activates a manager for use on the server

If an error occurs, an exception is raised.

Parameters:

• manager_version (str)

• programs (Dict[str, List[str]])

• compute_tags (List[str])

Return type:

int

deactivate(active_tasks, active_cores, active_memory, total_cpu_hours)

Parameters:

• active_tasks (int)

• active_cores (int)

• active_memory (float)

• total_cpu_hours (float)

Return type:

None

heartbeat(active_tasks, active_cores, active_memory, total_cpu_hours)

Parameters:

• active_tasks (int)

• active_cores (int)

• active_memory (float)

• total_cpu_hours (float)

Return type:

None

claim(programs, tags, limit)

Parameters:

• programs (Dict[str, List[str]])

• tags (List[str])

• limit (int)

Return type:

List[RecordTask]

return_finished(results_compressed)

Parameters:

results_compressed (Dict[int, bytes])

Return type:

TaskReturnMetadata

download_file(endpoint, destination_path, overwrite=False, expected_size=None, show_progress=False)

Download a file with optional progress bar

Parameters:

• endpoint (str) – API endpoint to download from

• destination_path (str) – Where to save the file

• overwrite (bool) – Whether to overwrite existing files

• expected_size (int | None) – Expected size of the file in bytes (used for progress bar if enabled)

• show_progress (bool) – Whether to show a progress bar during download

Returns:

A tuple of the size of the downloaded file (in bytes) and its sha256 checksum

Return type:

tuple[int, str]

property encoding: str

classmethod from_env()

Creates a new client given information stored in environment variables

The environment variables are:

• QCPORTAL_ADDRESS (required)

• QCPORTAL_USERNAME (optional)

• QCPORTAL_PASSWORD (optional)

• QCPORTAL_API_TOKEN (optional, mutually exclusive with username/password)

• QCPORTAL_VERIFY (optional, defaults to True)

• QCPORTAL_CACHE_DIR (optional)

Returns:

A new client, constructed with the settings found in the environment

Return type:

_ClientType

classmethod from_file(server_name=None, config_path=None)

Creates a new client given information in a file.

If no path is passed in, the current working directory and finally ~/.qca are searched for “qcportal_config.yaml”

Parameters:

• server_name (str | None) – Name/alias of the server in the yaml file

• config_path (str | None) – Full path to a configuration file, or a directory containing “qcportal_config.yaml”.

Returns:

A new client, constructed with the settings found in the file

Return type:

_ClientType

get_server_information()

Request general information about the server

Returns:

Server information.

Return type:

dict[str, Any]

make_request(method, endpoint, response_model, *, body_model=None, url_params_model=None, body=None, url_params=None, upload_files=None, allow_retries=True, additional_headers=None)

Parameters:

• method (str)

• endpoint (str)

• response_model (Any)

• body_model (Any)

• url_params_model (Any)

• body (Any)

• url_params (Any)

• upload_files (Iterable[tuple[str, str]] | None)

• allow_retries (bool)

• additional_headers (dict[str, Any] | None)

Return type:

Any

ping()

Pings the server to see if it is up

Returns:

True if the server is up and responded to the ping. False otherwise

Return type:

bool

username: str | None

user_id: int | None

server_info: dict[str, Any]

Caching for the PortalClient

compress_for_cache(data)

Parameters:

data (Any)

Return type:

bytes

decompress_from_cache(data, value_type)

Parameters:

data (bytes)

Return type:

Any

class RecordCache

Bases: object

__init__(cache_uri, read_only)

Parameters:

• cache_uri (str)

• read_only (bool)

update_metadata(key, value)

Parameters:

• key (str)

• value (Any)

Return type:

None

get_record(record_id, record_type)

Parameters:

• record_id (int)

• record_type (Type[_RECORD_T])

Return type:

_RECORD_T | None

get_records(record_ids, record_type)

Parameters:

• record_ids (Iterable[int])

• record_type (Type[_RECORD_T])

Return type:

list[_RECORD_T]

get_existing_records(record_ids)

Parameters:

record_ids (Iterable[int])

Return type:

list[int]

update_records(records)

Parameters:

records (Iterable[_RECORD_T])

writeback_record(record)

delete_record(record_id)

Parameters:

record_id (int)

delete_records(record_ids)

Parameters:

record_ids (Iterable[int])

class DatasetCache

Bases: RecordCache

__init__(cache_uri, read_only, dataset_type)

Parameters:

• cache_uri (str)

• read_only (bool)

• dataset_type (Type[_DATASET_T])

get_metadata(key)

Return type:

Any

entry_exists(name)

Parameters:

name (str)

Return type:

bool

get_entry_names()

Return type:

list[str]

get_entry(name)

Parameters:

name (str)

Return type:

BaseModel | None

get_entries(names)

Parameters:

names (Iterable[str])

Return type:

list[BaseModel]

update_entries(entries)

Parameters:

entries (Iterable[BaseModel])

rename_entry(old_name, new_name)

Parameters:

• old_name (str)

• new_name (str)

delete_entry(name)

specification_exists(name)

Parameters:

name (str)

Return type:

bool

get_specification_names()

Return type:

list[str]

get_specification(name)

Parameters:

name (str)

get_all_specifications()

Return type:

list[BaseModel]

get_specifications(names)

Parameters:

names (Iterable[str])

Return type:

list[BaseModel]

update_specifications(specifications)

Parameters:

specifications (Iterable[BaseModel])

rename_specification(old_name, new_name)

Parameters:

• old_name (str)

• new_name (str)

delete_specification(name)

dataset_record_exists(entry_name, specification_name)

Parameters:

• entry_name (str)

• specification_name (str)

Return type:

bool

get_dataset_record(entry_name, specification_name)

Parameters:

• entry_name (str)

• specification_name (str)

Return type:

_RECORD_T | None

get_dataset_records(entry_names, specification_names, status=None)

Parameters:

• entry_names (Iterable[str])

• specification_names (Iterable[str])

• status (Iterable[RecordStatusEnum] | None)

Return type:

list[tuple[str, str, _RECORD_T]]

update_dataset_records(record_info)

Parameters:

record_info (Iterable[tuple[str, str, int]])

delete_dataset_record(entry_name, specification_name)

Parameters:

• entry_name (str)

• specification_name (str)

delete_dataset_records(entry_names, specification_names)

Parameters:

• entry_names (Iterable[str] | None)

• specification_names (Iterable[str] | None)

get_dataset_record_info(entry_names, specification_names, status)

Parameters:

• entry_names (Iterable[str])

• specification_names (Iterable[str])

• status (Iterable[RecordStatusEnum] | None)

Return type:

list[tuple[str, str, int, RecordStatusEnum, datetime.datetime]]

get_existing_dataset_records(entry_names, specification_names)

Parameters:

• entry_names (Iterable[str])

• specification_names (Iterable[str])

Return type:

list[tuple[str, str, int]]

delete_record(record_id)

Parameters:

record_id (int)

delete_records(record_ids)

Parameters:

record_ids (Iterable[int])

get_existing_records(record_ids)

Parameters:

record_ids (Iterable[int])

Return type:

list[int]

get_record(record_id, record_type)

Parameters:

• record_id (int)

• record_type (Type[_RECORD_T])

Return type:

_RECORD_T | None

get_records(record_ids, record_type)

Parameters:

• record_ids (Iterable[int])

• record_type (Type[_RECORD_T])

Return type:

list[_RECORD_T]

update_metadata(key, value)

Parameters:

• key (str)

• value (Any)

Return type:

None

update_records(records)

Parameters:

records (Iterable[_RECORD_T])

writeback_record(record)

class PortalCache

Bases: object

__init__(server_uri, cache_dir, max_size)

Parameters:

• server_uri (str)

• cache_dir (str | None)

• max_size (int)

get_cache_path(cache_name)

Parameters:

cache_name (str)

Return type:

str

get_cache_uri(cache_name)

Parameters:

cache_name (str)

Return type:

str

get_dataset_cache_path(dataset_id)

Parameters:

dataset_id (int)

Return type:

str

get_dataset_cache_uri(dataset_id)

Parameters:

dataset_id (int)

Return type:

str

get_dataset_cache(dataset_id, dataset_type)

Parameters:

• dataset_id (int)

• dataset_type (Type[_DATASET_T])

Return type:

DatasetCache

property is_disk: bool

vacuum(cache_name=None)

Parameters:

cache_name (str | None)

read_dataset_metadata(file_path)

Reads the type of dataset stored in a cache file

This is needed sometimes to construct the DatasetCache object with a type

Parameters:

file_path (str)

get_records_with_cache(client, base_url_prefix, record_cache, record_type, record_ids, include=None, force_fetch=False)

Helper function for obtaining child records either from the cache or from the server

The records are returned in the same order as the record_ids parameter.

If records are missing from the cache, and client is None, and exception is raised.

Newly-fetched records will not be immediately written to the cache. Instead, they will be attached to this cache and will be written back to the cache when the record object is destructed.

If include is specified, additional fields will be fetched from the server. However, if the records are in the cache already, they may be missing those fields. In that case, the additional information may be fetched from the server. If a client is not provided, an exception will be raised.

This function will fetch the children of the records if enough information is fetched of the parent record. This is handled by the various fetch_children_multi class functions of the record types.

Parameters:

• client (PortalClient | None) – The client to use for fetching records from the server. If None, the function will only use the cache

• base_url_prefix (str) – Prefix of all the URLs for fetching records

• record_cache (RecordCache | None) – The cache to use for fetching records from the cache. If None, the function will only use the client

• record_type (Type[_RECORD_T]) – The type of record to fetch

• record_ids (Sequence[int]) – Single ID or sequence/list of records to obtain

• include (Iterable[str] | None) – Additional fields to include in the returned record (if fetching from the client)

• force_fetch (bool) – If True, the function will fetch all records from the server, regardless of whether they are in the cache

Returns:

List of records in the same order as the input record_ids.

Return type:

list[_RECORD_T]