QCPortal API Reference#

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

Bases: PortalClientBase

Main class for interacting with a QCArchive server

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 (Optional[str]) – The username to authenticate with.
password (Optional[str]) – 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 (Optional[str]) – Directory to store an internal cache of records and other data
cache_max_size (int) – Maximum size of the cache directory
memory_cache_key (Optional[str])

get_server_information()[source]#

Request general information about the server

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

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

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=True, default_tag='*', default_priority=PriorityEnum.normal, metadata=None, owner_group=None, existing_ok=False)[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_tag (str)
default_priority (PriorityEnum)
metadata (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)

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]]

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, status=None, dataset_id=None, parent_id=None, child_id=None, created_before=None, created_after=None, modified_before=None, modified_after=None, owner_user=None, owner_group=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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list (usernames or IDs)
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group in the given list (group names 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_tag=None, new_priority=None)[source]#

Modify the tag or priority of a record

Parameters:

record_ids (int | Sequence[int])
new_tag (str | None)
new_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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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 (AtomicResultProtocols | Dict[str, Any] | None) – Protocols for storing more/less data for each computation
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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, status=None, dataset_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, owner_user=None, owner_group=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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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)
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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, status=None, dataset_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, owner_user=None, owner_group=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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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, status=None, dataset_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, owner_user=None, owner_group=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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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, status=None, dataset_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, owner_user=None, owner_group=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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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 set of molecules

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
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (Optional[str]) – Group with additional permission for these records
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_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, status=None, dataset_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, owner_user=None, owner_group=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
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
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 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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, singlepoint_specification, keywords, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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 (QCSpecification) – Specification for the singlepoint calculations done in the expansion
keywords (ManybodyKeywords) – The keywords for the manybody program
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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_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, status=None, dataset_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, owner_user=None, owner_group=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
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
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 reaction 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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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, tag='*', priority=PriorityEnum.normal, owner_group=None, find_existing=True)[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 set of molecules

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 any optimizations of the torsiondrive should be run
keywords (NEBKeywords | Dict[str, Any]) – The torsiondrive keywords for the computation
tag (str) – The tag for the task. This will assist in routing to appropriate compute managers.
priority (PriorityEnum) – The priority of the job (high, normal, low). Default is normal.
owner_group (str | None) – Group with additional permission for these records
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_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, status=None, dataset_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, owner_user=None, owner_group=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
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
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
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
owner_user (int | str | Iterable[int | str] | None) – Query records owned by a user in the given list
owner_group (int | str | Iterable[int | str] | None) – Query records owned by a group 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_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_roles()[source]#

List all user roles on the server

Return type:: List[RoleInfo]

get_role(rolename)[source]#

Get information about a role on the server

Parameters:: rolename (str)
Return type:: RoleInfo

add_role(role_info)[source]#

Adds a role with permissions to the server

If not successful, an exception is raised.

Parameters:: role_info (RoleInfo)
Return type:: None

modify_role(role_info)[source]#

Modifies the permissions of a role on the server

If not successful, an exception is raised.

Returns:: A copy of the role as it now appears on the server
Parameters:: role_info (RoleInfo)
Return type:: RoleInfo

delete_role(rolename)[source]#

Deletes a role from the server

This will not delete any role to which a user is assigned

Will raise an exception on error

Parameters:: rolename (str) – Name of the role to delete
Return type:: None

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

property encoding: str#

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, allow_retries=True)#

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)
allow_retries (bool)

Return type:

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 MoleculeQueryIterator(client, query_filters)[source]#

Bases: QueryIteratorBase[Molecule]

Iterator for molecule queries

This iterator transparently handles batching and pagination over the results of a molecule query.

Construct an iterator

Parameters:

client – QCPortal client object used to contact/retrieve data from the server
query_filters (MoleculeQueryFilters) – The actual query information to send to the server

reset()#: Starts retrieval of results from the beginning again