REST API¶

The items in this list document the REST API calls which can be made against the server, this includes both the Body and the Responses for the various GET, POST, and PUT calls.

The entries are organized such that the API is presented first, separated by objects. The last group of entries are common models which are parts of the API Bodies and Responses (like Metadata), but occur many times in the normal calls.

KV Store¶

class qcportal.models.rest_models.KVStoreGETBody(*, meta: qcportal.models.rest_models.EmptyMeta = {}, data: qcportal.models.rest_models.KVStoreGETBody.Data)[source]¶

Parameters

meta (EmptyMeta, Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.
data (Data, Default: Ellipsis) – Data of the KV Get field: consists of Id of the Key/Value object to fetch.

class qcportal.models.rest_models.KVStoreGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: Dict[str, qcportal.models.common_models.KVStore])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (KVStore, Default: Ellipsis) – The entries of Key/Value object requested.

Molecule¶

class qcportal.models.rest_models.MoleculeGETBody(*, meta: qcportal.models.rest_models.QueryMeta = QueryMeta(limit=None, skip=0), data: qcportal.models.rest_models.MoleculeGETBody.Data)[source]¶

Parameters

meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information
data (Data, Default: Ellipsis) – Data fields for a Molecule query.

class qcportal.models.rest_models.MoleculeGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[qcelemental.models.molecule.Molecule])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (Molecule, Default: Ellipsis) – The List of Molecule objects found by the query.

class qcportal.models.rest_models.MoleculePOSTBody(*, meta: qcportal.models.rest_models.EmptyMeta = {}, data: List[qcelemental.models.molecule.Molecule])[source]¶

Parameters

meta (EmptyMeta, Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.
data (Molecule, Default: Ellipsis) – A list of Molecule objects to add to the Database.

class qcportal.models.rest_models.MoleculePOSTResponse(*, meta: qcportal.models.rest_models.ResponsePOSTMeta, data: List[qcportal.models.common_models.ObjectId])[source]¶

Parameters

meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.
data (List[ObjectId], Default: Ellipsis) – A list of Id’s assigned to the Molecule objects passed in which serves as a unique identifier in the database. If the Molecule was already in the database, then the Id returned is its existing Id (entries are not duplicated).

Keywords¶

class qcportal.models.rest_models.KeywordGETBody(*, meta: qcportal.models.rest_models.QueryMeta = QueryMeta(limit=None, skip=0), data: qcportal.models.rest_models.KeywordGETBody.Data)[source]¶

Parameters

meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information
data (Data, Default: Ellipsis) – The formal query for a Keyword fetch, contains id or hash_index for the object to fetch.

class qcportal.models.rest_models.KeywordGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[qcportal.models.common_models.KeywordSet])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (KeywordSet, Default: Ellipsis) – The KeywordSet found from in the database based on the query.

class qcportal.models.rest_models.KeywordPOSTBody(*, meta: qcportal.models.rest_models.EmptyMeta = {}, data: List[qcportal.models.common_models.KeywordSet])[source]¶

Parameters

meta (EmptyMeta, Default: {}) – There is no metadata with this, so an empty metadata is sent for completion.
data (KeywordSet, Default: Ellipsis) – The list of KeywordSet objects to add to the database.

class qcportal.models.rest_models.KeywordPOSTResponse(*, data: List[Optional[qcportal.models.common_models.ObjectId]], meta: qcportal.models.rest_models.ResponsePOSTMeta)[source]¶

Parameters

data (List[ObjectId], Default: Ellipsis) – The Ids assigned to the added KeywordSet objects. In the event of duplicates, the Id will be the one already found in the database.
meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.

Collections¶

class qcportal.models.rest_models.CollectionGETBody(*, meta: qcportal.models.rest_models.QueryFilter = None, data: qcportal.models.rest_models.CollectionGETBody.Data)[source]¶

Parameters

meta (QueryFilter, Optional) – Additional metadata to make with the query. Collections can only have an include/exclude key in its meta and therefore does not follow the standard GET metadata model.
data (Data, Default: Ellipsis) – Information about the Collection to search the database with.

class qcportal.models.rest_models.CollectionGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[Dict[str, Optional[Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (List[Dict[str, Optional[Any]]], Default: Ellipsis) – The Collection objects returned by the server based on the query.

class qcportal.models.rest_models.CollectionPOSTBody(*, meta: qcportal.models.rest_models.CollectionPOSTBody.Meta = Meta(overwrite=False), data: qcportal.models.rest_models.CollectionPOSTBody.Data)[source]¶

Parameters

meta (Meta, Optional) – Metadata to specify how the Database should handle adding this Collection if it already exists. Metadata model for adding Collections can only accept overwrite as a key to choose to update existing Collections or not.
data (Data, Default: Ellipsis) – The data associated with this Collection to add to the database.

class qcportal.models.rest_models.CollectionPOSTResponse(*, data: str, meta: qcportal.models.rest_models.ResponsePOSTMeta)[source]¶

Parameters

data (str, Default: Ellipsis) – The Id of the Collection uniquely pointing to it in the Database. If the Collection was not added (e.g. overwrite=False for existing Collection), then a None is returned.
meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.

Result¶

class qcportal.models.rest_models.ResultGETBody(*, meta: qcportal.models.rest_models.QueryMetaFilter = QueryMetaFilter(include=None, exclude=None, limit=None, skip=0), data: qcportal.models.rest_models.ResultGETBody.Data)[source]¶

Parameters

meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination
data (Data, Default: Ellipsis) – The keys with data to search the database on for individual quantum chemistry computations.

class qcportal.models.rest_models.ResultGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: Union[List[qcportal.models.records.ResultRecord], List[Dict[str, Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (Union[ResultRecord, List[Dict[str, Any]]], Default: Ellipsis) – Results found from the query. This is a list of ResultRecord in most cases, however, if a projection was specified in the GET request, then a dict is returned with mappings based on the projection.

Procedures¶

class qcportal.models.rest_models.ProcedureGETBody(*, meta: qcportal.models.rest_models.QueryMetaFilter = QueryMetaFilter(include=None, exclude=None, limit=None, skip=0), data: qcportal.models.rest_models.ProcedureGETBody.Data)[source]¶

Parameters

meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination
data (Data, Default: Ellipsis) – The keys with data to search the database on for Procedures.

class qcportal.models.rest_models.ProcedureGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[Dict[str, Optional[Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (List[Dict[str, Optional[Any]]], Default: Ellipsis) – The list of Procedure specs found based on the query.

Task Queue¶

class qcportal.models.rest_models.TaskQueueGETBody(*, meta: qcportal.models.rest_models.QueryMetaFilter = QueryMetaFilter(include=None, exclude=None, limit=None, skip=0), data: qcportal.models.rest_models.TaskQueueGETBody.Data)[source]¶

Parameters

meta (QueryMetaFilter, Optional) – Fractal Server metadata for Database queries allowing for filtering and pagination
data (Data, Default: Ellipsis) – The keys with data to search the database on for Tasks.

class qcportal.models.rest_models.TaskQueueGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: Union[List[qcportal.models.task_models.TaskRecord], List[Dict[str, Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (Union[TaskRecord, List[Dict[str, Any]]], Default: Ellipsis) – Tasks found from the query. This is a list of TaskRecord in most cases, however, if a projection was specified in the GET request, then a dict is returned with mappings based on the projection.

class qcportal.models.rest_models.TaskQueuePOSTBody(*, meta: qcportal.models.rest_models.TaskQueuePOSTBody.Meta, data: List[Union[qcportal.models.common_models.ObjectId, qcelemental.models.molecule.Molecule]])[source]¶

Parameters

meta (Meta, Default: Ellipsis) – The additional specification information for the Task to add to the Database.
data (List[Union[ObjectId, Molecule]], Default: Ellipsis) – The list of either Molecule objects or Molecule Id’s (those already in the database) to submit as part of this Task.

class qcportal.models.rest_models.TaskQueuePOSTResponse(*, meta: qcportal.models.rest_models.ResponsePOSTMeta, data: qcportal.models.rest_models.ComputeResponse)[source]¶

Parameters

meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.
data (ComputeResponse, Default: Ellipsis) – Data returned from the server from adding a Task.

class qcportal.models.rest_models.TaskQueuePUTBody(*, meta: qcportal.models.rest_models.TaskQueuePUTBody.Meta, data: qcportal.models.rest_models.TaskQueuePUTBody.Data)[source]¶

Parameters

meta (Meta, Default: Ellipsis) – The instructions to pass to the target Task from data.
data (Data, Default: Ellipsis) – The information which contains the Task target in the database.

class qcportal.models.rest_models.TaskQueuePUTResponse(*, meta: qcportal.models.rest_models.ResponseMeta, data: qcportal.models.rest_models.TaskQueuePUTResponse.Data)[source]¶

Parameters

meta (ResponseMeta, Default: Ellipsis) – Standard Fractal Server response metadata
data (Data, Default: Ellipsis) – Information returned from attempting updates of Tasks.

Service Queue¶

class qcportal.models.rest_models.ServiceQueueGETBody(*, meta: qcportal.models.rest_models.QueryMeta = QueryMeta(limit=None, skip=0), data: qcportal.models.rest_models.ServiceQueueGETBody.Data)[source]¶

Parameters

meta (QueryMeta, Optional) – Standard Fractal Server metadata for Database queries containing pagination information
data (Data, Default: Ellipsis) – The keys with data to search the database on for Services.

class qcportal.models.rest_models.ServiceQueueGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[Dict[str, Optional[Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (List[Dict[str, Optional[Any]]], Default: Ellipsis) – The return of Services found in the database mapping their Ids to the Service spec.

class qcportal.models.rest_models.ServiceQueuePOSTBody(*, meta: qcportal.models.rest_models.ServiceQueuePOSTBody.Meta, data: List[Union[qcportal.models.torsiondrive.TorsionDriveInput, qcportal.models.gridoptimization.GridOptimizationInput]])[source]¶

Parameters

meta (Meta, Default: Ellipsis) – Metadata information for the Service for the Tag and Priority of Tasks this Service will create.
data (List[Union[TorsionDriveInput, GridOptimizationInput]], Default: Ellipsis) – A list the specification for Procedures this Service will manage and generate Tasks for.

class qcportal.models.rest_models.ServiceQueuePOSTResponse(*, meta: qcportal.models.rest_models.ResponsePOSTMeta, data: qcportal.models.rest_models.ComputeResponse)[source]¶

Parameters

meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.
data (ComputeResponse, Default: Ellipsis) – Data returned from the server from adding a Service.

class qcportal.models.rest_models.ServiceQueuePUTBody(*, meta: qcportal.models.rest_models.ServiceQueuePUTBody.Meta, data: qcportal.models.rest_models.ServiceQueuePUTBody.Data)[source]¶

Parameters

meta (Meta, Default: Ellipsis) – The instructions to pass to the targeted Service.
data (Data, Default: Ellipsis) – The information which contains the Service target in the database.

class qcportal.models.rest_models.ServiceQueuePUTResponse(*, meta: qcportal.models.rest_models.ResponseMeta, data: qcportal.models.rest_models.ServiceQueuePUTResponse.Data)[source]¶

Parameters

meta (ResponseMeta, Default: Ellipsis) – Standard Fractal Server response metadata
data (Data, Default: Ellipsis) – Information returned from attempting updates of Services.

Queue Manager¶

class qcportal.models.rest_models.QueueManagerGETBody(*, meta: qcportal.models.rest_models.QueueManagerMeta, data: qcportal.models.rest_models.QueueManagerGETBody.Data)[source]¶

Parameters

meta (QueueManagerMeta, Default: Ellipsis) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.
data (Data, Default: Ellipsis) – A model of Task request data for the Queue Manager to fetch. Accepts limit as the maximum number of tasks to pull.

class qcportal.models.rest_models.QueueManagerGETResponse(*, meta: qcportal.models.rest_models.ResponseGETMeta, data: List[Dict[str, Optional[Any]]])[source]¶

Parameters

meta (ResponseGETMeta, Default: Ellipsis) – Standard Fractal Server response metadata for GET/fetch type requests.
data (List[Dict[str, Optional[Any]]], Default: Ellipsis) – A list of tasks retrieved from the server to compute.

class qcportal.models.rest_models.QueueManagerPOSTBody(*, meta: qcportal.models.rest_models.QueueManagerMeta, data: Dict[qcportal.models.common_models.ObjectId, Any])[source]¶

Parameters

meta (QueueManagerMeta, Default: Ellipsis) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.
data (Dict[ObjectId, Any], Default: Ellipsis) – A Dictionary of tasks to return to the server.

class qcportal.models.rest_models.QueueManagerPOSTResponse(*, meta: qcportal.models.rest_models.ResponsePOSTMeta, data: bool)[source]¶

Parameters

meta (ResponsePOSTMeta, Default: Ellipsis) – Standard Fractal Server response metadata for POST/add type requests.
data (bool, Default: Ellipsis) – A True/False return on if the server accepted the returned tasks.

class qcportal.models.rest_models.QueueManagerPUTBody(*, meta: qcportal.models.rest_models.QueueManagerMeta, data: qcportal.models.rest_models.QueueManagerPUTBody.Data)[source]¶

Parameters

meta (QueueManagerMeta, Default: Ellipsis) – Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.
data (Data, Default: Ellipsis) – The update action which the Queue Manager requests the Server take with respect to how the Queue Manager is tracked.

class qcportal.models.rest_models.QueueManagerPUTResponse(*, meta: Dict[str, Any] = {}, data: Union[Dict[str, int], bool])[source]¶

Parameters

meta (Dict[str, Any], Default: {}) – There is no metadata accepted, so an empty metadata is sent for completion.
data (Union[name=’data_Dict[str, int]’ type=Mapping[str, int] required=True, bool], Default: Ellipsis) – The response from the Server attempting to update the Queue Manager’s server-side status. Response type is a function of the operation made from the PUT request.

Common REST Components¶

These are NOT complete Body or Responses to the REST API, but common fragments which make up things like the Metadata or the Data fields.

class qcportal.models.rest_models.EmptyMeta[source]¶: There is no metadata accepted, so an empty metadata is sent for completion.

class qcportal.models.rest_models.ResponseMeta(*, errors: List[Tuple[str, str]], success: bool, error_description: Union[str, bool])[source]¶

Standard Fractal Server response metadata

Parameters

errors (List[Tuple[str, str]], Default: Ellipsis) – A list of error pairs in the form of [(error type, error message), …]
success (bool, Default: Ellipsis) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.
error_description (Union[str, bool], Default: Ellipsis) – Details about the error if success is False, otherwise this is False in the event of no errors.

class qcportal.models.rest_models.ResponseGETMeta(*, errors: List[Tuple[str, str]], success: bool, error_description: Union[str, bool], missing: List[str], n_found: int)[source]¶

Standard Fractal Server response metadata for GET/fetch type requests.

Parameters

errors (List[Tuple[str, str]], Default: Ellipsis) – A list of error pairs in the form of [(error type, error message), …]
success (bool, Default: Ellipsis) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.
error_description (Union[str, bool], Default: Ellipsis) – Details about the error if success is False, otherwise this is False in the event of no errors.
missing (List[str], Default: Ellipsis) – The Id’s of the objects which were not found in the database.
n_found (int, Default: Ellipsis) – The number of entries which were already found in the database from the set which was provided.

class qcportal.models.rest_models.ResponsePOSTMeta(*, errors: List[Tuple[str, str]], success: bool, error_description: Union[str, bool], n_inserted: int, duplicates: Union[List[str], List[Tuple[str, str]]], validation_errors: List[str])[source]¶

Standard Fractal Server response metadata for POST/add type requests.

Parameters

errors (List[Tuple[str, str]], Default: Ellipsis) – A list of error pairs in the form of [(error type, error message), …]
success (bool, Default: Ellipsis) – Indicates if the passed information was successful in its duties. This is contextual to the data being passed in.
error_description (Union[str, bool], Default: Ellipsis) – Details about the error if success is False, otherwise this is False in the event of no errors.
n_inserted (int, Default: Ellipsis) – The number of new objects amongst the inputs which did not exist already, and are now in the database.
duplicates (Union[List[str], List[Tuple[str, str]]], Default: Ellipsis) – The Ids of the objects which already exist in the database amongst the set which were passed in.
validation_errors (List[str], Default: Ellipsis) – All errors with validating submitted objects will be documented here.

class qcportal.models.rest_models.QueryMeta(*, limit: int = None, skip: int = 0)[source]¶

Standard Fractal Server metadata for Database queries containing pagination information

Parameters

limit (int, Optional) – Limit to the number of objects which can be returned with this query.
skip (int, Default: 0) – The number of records to skip on the query.

class qcportal.models.rest_models.QueueManagerMeta(*, cluster: str, hostname: str, uuid: str, username: str = None, qcengine_version: str, manager_version: str, programs: List[str], procedures: List[str], tag: Optional[Union[List[str], str]] = None, total_worker_walltime: float = None, total_task_walltime: float = None, active_tasks: int = None, active_cores: int = None, active_memory: float = None)[source]¶

Validation and identification Meta information for the Queue Manager’s communication with the Fractal Server.

Parameters

cluster (str, Default: Ellipsis) – The Name of the Cluster the Queue Manager is running on.
hostname (str, Default: Ellipsis) – Hostname of the machine the Queue Manager is running on.
uuid (str, Default: Ellipsis) – A UUID assigned to the QueueManager to uniquely identify it.
username (str, Optional) – Fractal Username the Manager is being executed under.
qcengine_version (str, Default: Ellipsis) – Version of QCEngine which the Manager has access to.
manager_version (str, Default: Ellipsis) – Version of the QueueManager (Fractal) which is getting and returning Jobs.
programs (List[str], Default: Ellipsis) – A list of programs which the QueueManager, and thus QCEngine, has access to. Affects which Tasks the Manager can pull.
procedures (List[str], Default: Ellipsis) – A list of procedures which the QueueManager has access to. Affects which Tasks the Manager can pull.
tag (Union[List[str], str], Optional) – Optional queue tag to pull Tasks from. If None, tasks are pulled from all tags. If a list of tags is provided, tasks are pulled in order of tags. (This does not guarantee tasks will be executed in that order, however.)
total_worker_walltime (float, Optional) – The total worker walltime in core-hours.
total_task_walltime (float, Optional) – The total task walltime in core-hours.
active_tasks (int, Optional) – The total number of active running tasks.
active_cores (int, Optional) – The total number of active cores.
active_memory (float, Optional) – The total amount of active memory in GB.