QCPortal Clients#

pretty_print_request(req)[source]#

pretty_print_response(res)[source]#

exception PortalRequestError[source]#

Bases: Exception

__init__(msg, status_code, details)[source]#

Parameters:

msg (str)
status_code (int)
details (Dict[str, Any])

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[source]#

Bases: object

__init__(address, username=None, password=None, verify=True, show_motd=True, *, information_endpoint='api/v1/information')[source]#

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
information_endpoint (str)

Return type:

None

classmethod from_file(server_name=None, config_path=None)[source]#

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”.

classmethod from_env()[source]#

Creates a new client given information stored in environment variables

The environment variables are:

QCPORTAL_ADDRESS (required)

QCPORTAL_USERNAME (optional)

QCPORTAL_PASSWORD (optional)

QCPORTAL_VERIFY (optional, defaults to True)

QCPORTAL_CACHE_DIR (optional)

property encoding: str#

make_request(method: str, endpoint: str, response_model: Type[_V], *, body_model: Type[_T] | None = None, url_params_model: Type[_U] | None = None, body: _T | Dict[str, Any] | None = None, url_params: _U | Dict[str, Any] | None = None, upload_files: Iterable[Tuple[str, str]] | None = None, allow_retries: bool = True, additional_headers: Dict[str, Any] | None = None) → _V[source]#

make_request(method: str, endpoint: str, response_model: None, *, body_model: Type[_T] | None = None, url_params_model: Type[_U] | None = None, body: _T | Dict[str, Any] | None = None, url_params: _U | Dict[str, Any] | None = None, upload_files: Iterable[Tuple[str, str]] | None = None, allow_retries: bool = True, additional_headers: Dict[str, Any] | None = None) → None

Parameters:

method (str)
endpoint (str)
response_model (Type[_V] | None)
body_model (Type[_T] | None)
url_params_model (Type[_U] | None)
body (_T | Dict[str, Any] | None)
url_params (_U | Dict[str, Any] | None)
upload_files (Iterable[Tuple[str, str]] | None)
allow_retries (bool)
additional_headers (Dict[str, Any] | None)

Return type:

_V | None

download_file(endpoint, destination_path, overwrite=False, expected_size=None, show_progress=False)[source]#

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

Return type:

Tuple[int, str]

ping()[source]#

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()[source]#

Request general information about the server

Returns:: Server information.
Return type:: Dict[str, Any]

class PortalClient[source]#

Bases: PortalClientBase

Main class for interacting with a QCArchive server

__init__(address, username=None, password=None, verify=True, show_motd=True, *, cache_dir=None, cache_max_size=0)[source]#

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
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()[source]#

Request general information about the server

Returns:: Server information.
Return type:: Dict[str, Any]

get_server_openapi_spec()[source]#

Request the OpenAPI specification for the server

Returns:: OpenAPI specification.
Return type:: Dict[str, Any]

get_server_stats()[source]#

Request statistics about the server

Returns:: Server statistics.
Return type:: List[ServerStatsEntry]

get_motd()[source]#

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

Return type:: str

set_motd(new_motd)[source]#

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

Parameters:: new_motd (str)
Return type:: str

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

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)[source]#

Obtain a project by name

The name is matched case-insensitively.

Parameters:: project_name (str)
Return type:: Project

get_project_by_id(project_id)[source]#

Obtain a project by ID

Parameters:: project_id (int)
Return type:: Project

delete_project(project_id, delete_records=False, delete_datasets=False, delete_dataset_records=False)[source]#

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

list_projects()[source]#

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)[source]#

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.

Returns:: A list of dictionaries, each with the keys record_id, project_id, project_name, and record_name
Parameters:: record_id (int | Iterable[int])
Return type:: List[Dict]

query_project_datasets(dataset_id)[source]#

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 record_id (which holds the dataset ID), project_id, project_name, and dataset_name
Return type:: List[Dict]

list_datasets()[source]#

list_datasets_table()[source]#

Return type:: str

print_datasets_table()[source]#

Return type:: None

get_dataset(dataset_type, dataset_name)[source]#

Parameters:

dataset_type (str)
dataset_name (str)

query_dataset_records(record_id, dataset_type=None)[source]#

Parameters:

record_id (int | Iterable[int])
dataset_type (Iterable[str] | None)

get_dataset_by_id(dataset_id)[source]#

Parameters:: dataset_id (int)

dataset_from_cache(file_path)[source]#

Parameters:: file_path (str)
Return type:: BaseDataset

create_dataset_view(dataset_id, file_path, include=None, overwrite=False)[source]#

Parameters:

dataset_id (int)
file_path (str)
include (Iterable[str] | None)
overwrite (bool)

get_dataset_status_by_id(dataset_id)[source]#

Parameters:: dataset_id (int)
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)[source]#

Parameters:

dataset_type (str)
name (str)
description (str | None)
tagline (str | None)
tags (List[str] | None)
group (str | None)
provenance (Dict[str, Any] | None)
visibility (bool)
default_compute_tag (str)
default_compute_priority (PriorityEnum)
extras (Dict[str, Any] | None)
owner_group (str | None)
existing_ok (bool)

Return type:

BaseDataset

delete_dataset(dataset_id, delete_records)[source]#

Parameters:

dataset_id (int)
delete_records (bool)

clone_dataset(source_dataset_id, new_dataset_name)[source]#

Parameters:

source_dataset_id (int)
new_dataset_name (str)

get_external_file_direct_link(file_id)[source]#

Parameters:: file_id (int)
Return type:: str

download_external_file(file_id, destination_path, overwrite=False)[source]#

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, missing_ok=False)[source]#

Obtains molecules with the specified IDs from the server

Parameters:

molecule_ids (int | Sequence[int]) – A single molecule ID, or a list (or other sequence) of molecule IDs
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 sequence of ids, the return value will be a list. Otherwise, it will be a single Molecule.

Return type:

Molecule | None | List[Molecule | None]

query_molecules(*, molecule_hash=None, molecular_formula=None, identifiers=None, limit=None)[source]#

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)[source]#

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)[source]#

Parameters:: file_paths (List[str])
Return type:: Tuple[Dict[str, List[Tuple[str, int]]], List[str]]

modify_molecule(molecule_id, name=None, comment=None, identifiers=None, overwrite_identifiers=False)[source]#

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)[source]#

Deletes molecules from the server

This will not delete any molecules that are in use

Parameters:: molecule_ids (int | Sequence[int]) – An id or list of ids to query.
Returns:: Metadata about what was deleted
Return type:: DeleteMetadata

get_records(record_ids, missing_ok=False, *, include=None)[source]#

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.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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:

A list of records. If missing_ok was specified, None will be substituted for a record that was not found.

Return type:

List[BaseRecord | None] | BaseRecord | 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)[source]#

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) – 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)[source]#

Resets running or errored records to be waiting again

Parameters:: record_ids (int | Sequence[int])
Return type:: UpdateMetadata

cancel_records(record_ids)[source]#

Marks running, waiting, or errored records as cancelled

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

Parameters:: record_ids (int | Sequence[int])
Return type:: UpdateMetadata

invalidate_records(record_ids)[source]#

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 | Sequence[int])
Return type:: UpdateMetadata

delete_records(record_ids, soft_delete=True, delete_children=True)[source]#

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 | Sequence[int]) – Reset the status of these record ids
soft_delete – Don’t actually delete the record, just mark it for later deletion
delete_children (bool) – If True, attempt to delete child records as well

Return type:

DeleteMetadata

uninvalidate_records(record_ids)[source]#

Undo the invalidation of records

Parameters:: record_ids (int | Sequence[int])
Return type:: UpdateMetadata

uncancel_records(record_ids)[source]#

Undo the cancellation of records

Parameters:: record_ids (int | Sequence[int])
Return type:: UpdateMetadata

undelete_records(record_ids)[source]#

Undo the (soft) deletion of records

Parameters:: record_ids (int | Sequence[int])
Return type:: UpdateMetadata

modify_records(record_ids, new_compute_tag=None, new_compute_priority=None, **kwargs)[source]#

Modify the compute tag or compute priority of a record

Parameters:

record_ids (int | Sequence[int])
new_compute_tag (str | None)
new_compute_priority (PriorityEnum | None)

Return type:

UpdateMetadata

add_comment(record_ids, comment)[source]#

Adds a comment to records

Parameters:

record_ids (int | Sequence[int]) – The record or records to add the comments to
comment (str) – The comment string to add. Your username will be added automatically

Returns:

Metadata about which records were updated

Return type:

UpdateMetadata

get_waiting_reason(record_id)[source]#

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)[source]#

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 | List[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 (str) – 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

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, missing_ok=False, *, include=None)[source]#

Obtain singlepoint records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[SinglepointRecord | 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)[source]#

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)[source]#

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 | List[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

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, missing_ok=False, *, include=None)[source]#

Obtain optimization records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[OptimizationRecord | 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)[source]#

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)[source]#

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 (List[List[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

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, missing_ok=False, *, include=None)[source]#

Obtain torsiondrive records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[TorsiondriveRecord | 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)[source]#

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)[source]#

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

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, missing_ok=False, *, include=None)[source]#

Obtain gridoptimization records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[GridoptimizationRecord | 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)[source]#

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)[source]#

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[Sequence[float, Union[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 (Optional[QCSpecification]) – The specification for singlepoint energy calculations
optimization_specification (Optional[OptimizationSpecification]) – 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

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, missing_ok=False, *, include=None)[source]#

Obtain reaction records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[ReactionRecord | 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)[source]#

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)[source]#

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”)
singlepoint_specification – Specification for the singlepoint calculations done in the expansion
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
levels (Dict[int | Literal['supersystem'], ~qcportal.singlepoint.record_models.QCSpecification])
bsse_correction (BSSECorrectionEnum | Sequence[BSSECorrectionEnum])

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_manybodys(record_ids, missing_ok=False, *, include=None)[source]#

Obtain manybody records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[ManybodyRecord | 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)[source]#

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 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)[source]#

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 (List[List[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

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, missing_ok=False, *, include=None)[source]#

Obtain NEB records with the specified IDs.

Records will be returned in the same order as the record ids.

Parameters:

record_ids (int | Sequence[int]) – Single ID or sequence/list of records 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 | None | List[NEBRecord | 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)[source]#

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, missing_ok=False)[source]#

Obtain manager information from the server with the specified names

Parameters:

names (str | Sequence[str]) – A manager name or list of names
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. If missing_ok was specified, None will be substituted for a manager that was not found.

Return type:

ComputeManager | None | List[ComputeManager | None]

query_managers(*, manager_id=None, name=None, cluster=None, hostname=None, status=None, modified_before=None, modified_after=None, limit=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

Gets information about an internal job on the server

Parameters:: job_id (int)
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)[source]#

Queries the internal job queue on the server

Parameters:

job_id (Optional[int, Iterable[int]]) – ID assigned to the job
name (Optional[Union[str, Iterable[str]]]) – Queries jobs whose name is in the given list
user (Optional[Union[int, str, Iterable[Union[int, str]]]]) – User name or ID associated with the log entry
runner_hostname (Optional[Union[str, Iterable[str]]]) – Queries jobs that were run/are running on a given host
status (Optional[Union[InternalJobStatusEnum, Iterable[InternalJobStatusEnum]]]) – Queries jobs whose status is in the given list
last_updated_before (Optional[Union[datetime, str]]) – Query for jobs last updated before a certain time
last_updated_after (Optional[Union[datetime, str]]) – Query for jobs last updated after a certain time
added_before (Optional[Union[datetime, str]]) – Query for jobs added before a certain time
added_after (Optional[Union[datetime, str]]) – Query for jobs added after a certain time
scheduled_before (Optional[Union[datetime, str]]) – Query for jobs scheduled to run before a certain time
scheduled_after (Optional[Union[datetime, str]]) – Query for jobs scheduled to run after a certain time
limit (Optional[int]) – 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)[source]#

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

Parameters:: job_id (int)

delete_internal_job(job_id)[source]#

Parameters:: job_id (int)

query_access_summary(*, group_by='day', before=None, after=None)[source]#

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

Return type:

AccessLogSummary

list_groups()[source]#

List all user groups on the server

Return type:: List[GroupInfo]

get_group(groupname_or_id)[source]#

Get information about a group on the server

Parameters:: groupname_or_id (int | str)
Return type:: GroupInfo

add_group(group_info)[source]#

Adds a group with permissions to the server

If not successful, an exception is raised.

Parameters:: group_info (GroupInfo)
Return type:: None

delete_group(groupname_or_id)[source]#

Deletes a group on the server

Deleted groups will be removed from all users groups list

Parameters:: groupname_or_id (int | str)

list_users()[source]#

List all user roles on the server

Return type:: List[UserInfo]

get_user(username_or_id=None)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

Delete a user from the server

Parameters:: username_or_id (int | str)
Return type:: None

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

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_VERIFY (optional, defaults to True)

QCPORTAL_CACHE_DIR (optional)

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”.

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 (Type[_V] | None)
body_model (Type[_T] | None)
url_params_model (Type[_U] | None)
body (_T | Dict[str, Any] | None)
url_params (_U | Dict[str, Any] | None)
upload_files (Iterable[Tuple[str, str]] | None)
allow_retries (bool)
additional_headers (Dict[str, Any] | None)

Return type:

_V | None

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

class ManagerClient[source]#

Bases: PortalClientBase

__init__(name_data, address='https://api.qcarchive.molssi.org', username=None, password=None, verify=True, show_motd=False)[source]#

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

Return type:

None

activate(manager_version, programs, compute_tags)[source]#

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)[source]#

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)[source]#

Parameters:

active_tasks (int)
active_cores (int)
active_memory (float)
total_cpu_hours (float)

Return type:

None

claim(programs, tags, limit)[source]#

Parameters:

programs (Dict[str, List[str]])
tags (List[str])
limit (int)

Return type:

List[RecordTask]

return_finished(results_compressed)[source]#

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

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_VERIFY (optional, defaults to True)

QCPORTAL_CACHE_DIR (optional)

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”.

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 (Type[_V] | None)
body_model (Type[_T] | None)
url_params_model (Type[_U] | None)
body (_T | Dict[str, Any] | None)
url_params (_U | Dict[str, Any] | None)
upload_files (Iterable[Tuple[str, str]] | None)
allow_retries (bool)
additional_headers (Dict[str, Any] | None)

Return type:

_V | None

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

Caching for the PortalClient

compress_for_cache(data)[source]#

Parameters:: data (Any)
Return type:: bytes

decompress_from_cache(data, value_type)[source]#

Parameters:: data (bytes)
Return type:: Any

class RecordCache[source]#

Bases: object

__init__(cache_uri, read_only)[source]#

Parameters:

cache_uri (str)
read_only (bool)

update_metadata(key, value)[source]#

Parameters:

key (str)
value (Any)

Return type:

None

get_record(record_id, record_type)[source]#

Parameters:

record_id (int)
record_type (Type[_RECORD_T])

Return type:

_RECORD_T | None

get_records(record_ids, record_type)[source]#

Parameters:

record_ids (Iterable[int])
record_type (Type[_RECORD_T])

Return type:

list[_RECORD_T]

get_existing_records(record_ids)[source]#

Parameters:: record_ids (Iterable[int])
Return type:: list[int]

update_records(records)[source]#

Parameters:: records (Iterable[_RECORD_T])

writeback_record(record)[source]#

delete_record(record_id)[source]#

Parameters:: record_id (int)

delete_records(record_ids)[source]#

Parameters:: record_ids (Iterable[int])

class DatasetCache[source]#

Bases: RecordCache

__init__(cache_uri, read_only, dataset_type)[source]#

Parameters:

cache_uri (str)
read_only (bool)
dataset_type (Type[_DATASET_T])

get_metadata(key)[source]#

Return type:: Any

entry_exists(name)[source]#

Parameters:: name (str)
Return type:: bool

get_entry_names()[source]#

Return type:: list[str]

get_entry(name)[source]#

Parameters:: name (str)
Return type:: BaseModel | None

get_entries(names)[source]#

Parameters:: names (Iterable[str])
Return type:: list[BaseModel]

update_entries(entries)[source]#

Parameters:: entries (Iterable[BaseModel])

rename_entry(old_name, new_name)[source]#

Parameters:

old_name (str)
new_name (str)

delete_entry(name)[source]#

specification_exists(name)[source]#

Parameters:: name (str)
Return type:: bool

get_specification_names()[source]#

Return type:: list[str]

get_specification(name)[source]#

Parameters:: name (str)

get_all_specifications()[source]#

Return type:: list[BaseModel]

get_specifications(names)[source]#

Parameters:: names (Iterable[str])
Return type:: list[BaseModel]

update_specifications(specifications)[source]#

Parameters:: specifications (Iterable[BaseModel])

rename_specification(old_name, new_name)[source]#

Parameters:

old_name (str)
new_name (str)

delete_specification(name)[source]#

dataset_record_exists(entry_name, specification_name)[source]#

Parameters:

entry_name (str)
specification_name (str)

Return type:

bool

get_dataset_record(entry_name, specification_name)[source]#

Parameters:

entry_name (str)
specification_name (str)

Return type:

_RECORD_T | None

get_dataset_records(entry_names, specification_names, status=None)[source]#

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)[source]#

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

delete_dataset_record(entry_name, specification_name)[source]#

Parameters:

entry_name (str)
specification_name (str)

delete_dataset_records(entry_names, specification_names)[source]#

Parameters:

entry_names (Iterable[str] | None)
specification_names (Iterable[str] | None)

get_dataset_record_info(entry_names, specification_names, status)[source]#

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)[source]#

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[source]#

Bases: object

__init__(server_uri, cache_dir, max_size)[source]#

Parameters:

server_uri (str)
cache_dir (str | None)
max_size (int)

get_cache_path(cache_name)[source]#

Parameters:: cache_name (str)
Return type:: str

get_cache_uri(cache_name)[source]#

Parameters:: cache_name (str)
Return type:: str

get_dataset_cache_path(dataset_id)[source]#

Parameters:: dataset_id (int)
Return type:: str

get_dataset_cache_uri(dataset_id)[source]#

Parameters:: dataset_id (int)
Return type:: str

get_dataset_cache(dataset_id, dataset_type)[source]#

Parameters:

dataset_id (int)
dataset_type (Type[_DATASET_T])

Return type:

DatasetCache

property is_disk: bool#

vacuum(cache_name=None)[source]#

Parameters:: cache_name (str | None)

read_dataset_metadata(file_path)[source]#

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)[source]#

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]