Reaction Records#

class ReactionKeywords[source]#: Bases: BaseModel

class ReactionSpecification[source]#

Bases: BaseModel

Fields#
Field	Type	Required	Default
`keywords`	`ReactionKeywords`	Yes
`optimization_specification`	`OptimizationSpecification` \| `None`	No	`None`
`program`	`str`	No	`'reaction'`
`singlepoint_specification`	`QCSpecification` \| `None`	No	`None`

Validators#
Validator	Mode	Fields
`required_spec`	after	model

program: LowerStr#

singlepoint_specification: QCSpecification | None#

optimization_specification: OptimizationSpecification | None#

keywords: ReactionKeywords#

required_spec()[source]#

class ReactionInput[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`record_type`	`Literal`[‘reaction’]	No	`'reaction'`
`specification`	`ReactionSpecification`	Yes
`stoichiometries`	`list`[`tuple`[`float`, `int` \| `Molecule`]]	Yes

record_type: Literal['reaction']#

specification: ReactionSpecification#

stoichiometries: list[tuple[float, int | Molecule]]#

class ReactionMultiInput[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`specification`	`ReactionSpecification`	Yes
`stoichiometries`	`list`[`list`[`tuple`[`float`, `int` \| `Molecule`]]]	Yes

specification: ReactionSpecification#

stoichiometries: list[list[tuple[float, int | Molecule]]]#

class ReactionAddBody[source]#

Bases: RecordAddBodyBase, ReactionMultiInput

Fields#
Field	Type	Required	Default
`compute_priority`	`PriorityEnum`	Yes
`compute_tag`	`str`	Yes
`find_existing`	`bool`	No	`True`
`specification`	`ReactionSpecification`	Yes
`stoichiometries`	`list`[`list`[`tuple`[`float`, `int` \| `Molecule`]]]	Yes

compute_tag#

compute_priority#

find_existing#

specification#

stoichiometries#

class ReactionQueryFilters[source]#

Bases: RecordQueryFilters

Fields#
Field	Type	Required	Default
`child_id`	`list`[`int`] \| `None`	No	`None`
`created_after`	`datetime` \| `None`	No	`None`
`created_before`	`datetime` \| `None`	No	`None`
`creator_user`	`list`[`int` \| `str`] \| `None`	No	`None`
`cursor`	`int` \| `None`	No	`None`
`dataset_id`	`list`[`int`] \| `None`	No	`None`
`history_manager_name`	`list`[`str`] \| `None`	No	`None`
`limit`	`int` \| `None`	No	`None`
`manager_name`	`list`[`str`] \| `None`	No	`None`
`modified_after`	`datetime` \| `None`	No	`None`
`modified_before`	`datetime` \| `None`	No	`None`
`molecule_id`	`list`[`int`] \| `None`	No	`None`
`optimization_program`	`list`[`Annotated`[`str`, `StringConstraints`(strip_whitespace=`None`, to_upper=`None`, to_lower=True, strict=`None`, min_length=`None`, max_length=`None`, pattern=`None`, ascii_only=`None`)]] \| `None`	No	`None`
`parent_id`	`list`[`int`] \| `None`	No	`None`
`program`	`list`[`str`] \| `None`	No	`None`
`project_id`	`list`[`int`] \| `None`	No	`None`
`qc_basis`	`list`[`Annotated`[`str`, `StringConstraints`(strip_whitespace=`None`, to_upper=`None`, to_lower=True, strict=`None`, min_length=`None`, max_length=`None`, pattern=`None`, ascii_only=`None`)] \| `None`] \| `None`	No	`None`
`qc_method`	`list`[`Annotated`[`str`, `StringConstraints`(strip_whitespace=`None`, to_upper=`None`, to_lower=True, strict=`None`, min_length=`None`, max_length=`None`, pattern=`None`, ascii_only=`None`)]] \| `None`	No	`None`
`qc_program`	`list`[`Annotated`[`str`, `StringConstraints`(strip_whitespace=`None`, to_upper=`None`, to_lower=True, strict=`None`, min_length=`None`, max_length=`None`, pattern=`None`, ascii_only=`None`)]] \| `None`	No	`None`
`record_id`	`list`[`int`] \| `None`	No	`None`
`record_type`	`list`[`str`] \| `None`	No	`None`
`status`	`list`[`RecordStatusEnum`] \| `None`	No	`None`

Validators#
Validator	Mode	Fields
`parse_dates`	before	`created_before`, `created_after`, `modified_before`, `modified_after`
`validate_lists`	before	`limit`, `cursor`

program: list[str] | None#

qc_program: list[LowerStr] | None#

qc_method: list[LowerStr] | None#

qc_basis: list[LowerStr | None] | None#

optimization_program: list[LowerStr] | None#

molecule_id: list[int] | None#

classmethod parse_dates(v)#

classmethod validate_lists(v)#

record_id#

record_type#

manager_name#

history_manager_name#

status#

dataset_id#

project_id#

parent_id#

child_id#

created_before#

created_after#

modified_before#

modified_after#

creator_user#

limit#

cursor#

class ReactionComponentMeta[source]#

Bases: BaseModel

Fields#
Field	Type	Required
`coefficient`	`float`	Yes
`molecule`	`Molecule` \| `None`	Yes
`molecule_id`	`int`	Yes
`optimization_id`	`int` \| `None`	Yes
`singlepoint_id`	`int` \| `None`	Yes

molecule_id: int#

coefficient: float#

singlepoint_id: int | None#

optimization_id: int | None#

molecule: Molecule | None#

class ReactionComponent[source]#

Bases: ReactionComponentMeta

Fields#
Field	Type	Required	Default
`coefficient`	`float`	Yes
`molecule`	`Molecule` \| `None`	Yes
`molecule_id`	`int`	Yes
`optimization_id`	`int` \| `None`	Yes
`optimization_record`	`OptimizationRecord` \| `None`	No	`None`
`singlepoint_id`	`int` \| `None`	Yes
`singlepoint_record`	`SinglepointRecord` \| `None`	No	`None`

singlepoint_record: SinglepointRecord | None#

optimization_record: OptimizationRecord | None#

molecule_id#

coefficient#

singlepoint_id#

optimization_id#

molecule#

class ReactionRecord[source]#

Bases: BaseRecord

Fields#
Field	Type	Required	Default	Alias
`comments_`	`list`[`RecordComment`] \| `None`	No	`None`	`comments`
`component_records_`	`list`[`ReactionComponent`] \| `None`	No	`None`	`component_records`
`components_meta_`	`list`[`ReactionComponentMeta`] \| `None`	No	`None`	`components`
`compute_history_`	`list`[`ComputeHistory`] \| `None`	No	`None`	`compute_history`
`created_on`	`datetime`	Yes
`creator_user`	`str` \| `None`	Yes
`description`	`str` \| `None`	No	`None`
`extras`	`dict`[`str`, `Any`]	No	`{}`
`id`	`int`	Yes
`is_service`	`bool`	Yes
`manager_name`	`str` \| `None`	Yes
`modified_on`	`datetime`	Yes
`name`	`str` \| `None`	No	`None`
`native_files_`	`dict`[`str`, `NativeFile`] \| `None`	No	`None`	`native_files`
`properties`	`dict`[`str`, `Any`] \| `None`	Yes
`record_type`	`Literal`[‘reaction’]	No	`'reaction'`
`service_`	`RecordService` \| `None`	No	`None`	`service`
`specification`	`ReactionSpecification`	Yes
`status`	`RecordStatusEnum`	Yes
`tags`	`list`[`str`] \| `None`	No	`None`
`task_`	`RecordTask` \| `None`	No	`None`	`task`
`total_energy`	`float` \| `None`	Yes

record_type: Literal['reaction']#

specification: ReactionSpecification#

total_energy: float | None#

components_meta_: list[ReactionComponentMeta] | None#

component_records_: list[ReactionComponent] | None#

propagate_client(client, base_url_prefix)[source]#

Propagates a client and related information to this record to any fields within this record that need it

This is expected to be called from derived class propagate_client functions as well

Parameters:: base_url_prefix (str | None)

get_cache_dict(**kwargs)[source]#

Returns a dictionary of the record meant for caching

When a record is stored in the cache, it is stored without child records (which are in the cache under their own keys). This function returns a dictionary that excludes those children.

kwargs are passed directly to the pydantic dict() function.

Return type:: dict[str, Any]

property components: list[ReactionComponent]#

__init__(client=None, base_url_prefix=None, **kwargs)#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: base_url_prefix (str | None)

property children_errors: list[BaseRecord]#: Returns errored child records

property children_status: dict[RecordStatusEnum, int]#: Returns a dictionary of the status of all children of this record

property comments: list[RecordComment] | None#

property compute_history: list[ComputeHistory]#

property error: dict[str, Any] | None#

fetch_children(include=None, force_fetch=False)#

Fetches all children of this record recursively

Parameters:

include (Iterable[str] | None)
force_fetch (bool)

classmethod fetch_children_multi(records, include=None, force_fetch=False)#

Fetches all children of the given records

This tries to work efficiently, fetching larger batches of children that can span multiple records

Parameters:

records (Iterable[BaseRecord | None])
include (Iterable[str] | None)
force_fetch (bool)

classmethod get_subclass(record_type)#

Obtain a subclass of this class given its record_type

Parameters:: record_type (str)
Return type:: Type[BaseRecord]

get_waiting_reason()#

Return type:: dict[str, Any]

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

property native_files: dict[str, NativeFile] | None#

property offline: bool#

property provenance: Provenance | None#

property service: RecordService | None#

property stderr: str | None#

property stdout: str | None#

sync_to_cache(detach=False)#

Syncs this record to the cache

If detach is True, then the record will be removed from the cache

Parameters:: detach (bool)

property task: RecordTask | None#

id#

is_service#

name#

description#

tags#

properties#

extras#

status#

manager_name#

created_on#

modified_on#

creator_user#

compute_history_#

task_#

service_#

comments_#

native_files_#

compare_reaction_records(record_1, record_2)[source]#

Parameters:

record_1 (ReactionRecord)
record_2 (ReactionRecord)

class ReactionDatasetEntryStoichiometry[source]#

Bases: BaseModel

Fields#
Field	Type	Required	Default
`coefficient`	`float`	Yes
`molecule`	`Molecule`	Yes

coefficient: float#

molecule: Molecule#

class ReactionDatasetNewEntry[source]#

Bases: BaseModel

Fields#
Field	Type	Required	Default
`additional_keywords`	`dict`[`str`, `Any`]	No	`{}`
`attributes`	`dict`[`str`, `Any`]	No	`{}`
`comment`	`str` \| `None`	No	`None`
`name`	`str`	Yes
`stoichiometries`	`list`[`ReactionDatasetEntryStoichiometry` \| `tuple`[`float`, `int` \| `Molecule`]]	Yes

name: str#

stoichiometries: list[ReactionDatasetEntryStoichiometry | tuple[float, int | Molecule]]#

additional_keywords: dict[str, Any]#

attributes: dict[str, Any]#

comment: str | None#

class ReactionDatasetEntry[source]#

Bases: ReactionDatasetNewEntry

Fields#
Field	Type	Required	Default
`additional_keywords`	`dict`[`str`, `Any`]	No	`{}`
`attributes`	`dict`[`str`, `Any`]	No	`{}`
`comment`	`str` \| `None`	No	`None`
`name`	`str`	Yes
`stoichiometries`	`list`[`ReactionDatasetEntryStoichiometry`]	Yes

stoichiometries: list[ReactionDatasetEntryStoichiometry]#

name#

additional_keywords#

attributes#

comment#

class ReactionDatasetSpecification[source]#

Bases: BaseModel

Fields#
Field	Type	Required	Default
`description`	`str` \| `None`	No	`None`
`name`	`str`	Yes
`specification`	`ReactionSpecification`	Yes

name: str#

specification: ReactionSpecification#

description: str | None#

class ReactionDatasetRecordItem[source]#

Bases: BaseModel

Fields#
Field	Type	Required
`entry_name`	`str`	Yes
`record`	`ReactionRecord` \| `None`	Yes
`record_id`	`int`	Yes
`specification_name`	`str`	Yes

entry_name: str#

specification_name: str#

record_id: int#

record: ReactionRecord | None#

class ReactionDataset[source]#

Bases: BaseDataset

Fields#
Field	Type	Required	Default	Alias
`attachments_`	`list`[`DatasetAttachment`] \| `None`	No	`None`	`attachments`
`auto_fetch_missing`	`bool`	No	`True`
`contributed_values_`	`dict`[`str`, `ContributedValues`] \| `None`	No	`None`	`contributed_values`
`creator_user`	`str` \| `None`	Yes
`dataset_type`	`Literal`[‘reaction’]	No	`'reaction'`
`default_compute_priority`	`PriorityEnum`	Yes
`default_compute_tag`	`str`	Yes
`description`	`str`	Yes
`extras`	`dict`[`str`, `Any`]	Yes
`id`	`int`	Yes
`name`	`str`	Yes
`provenance`	`dict`[`str`, `Any`]	Yes
`tagline`	`str`	Yes
`tags`	`list`[`str`]	Yes

dataset_type: Literal['reaction']#

add_specification(name, specification, description=None)[source]#

Parameters:

name (str)
specification (ReactionSpecification)
description (str | None)

Return type:

InsertMetadata

add_entries(entries)[source]#

Parameters:: entries (ReactionDatasetNewEntry | Iterable[ReactionDatasetNewEntry])
Return type:: InsertMetadata

background_add_entries(entries)[source]#

Parameters:: entries (ReactionDatasetNewEntry | Iterable[ReactionDatasetNewEntry])
Return type:: InternalJob

add_entry(name, stoichiometries, additional_keywords=None, attributes=None, comment=None)[source]#

Parameters:

name (str)
stoichiometries (list[tuple[float, int | Molecule]])
additional_keywords (dict[str, Any] | None)
attributes (dict[str, Any] | None)
comment (str | None)

__init__(client=None, base_url_prefix=None, cache_data=None, **kwargs)#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

client (PortalClient | None)
base_url_prefix (str | None)
cache_data (DatasetCache | None)

assert_is_not_view()#

assert_online()#

property attachments: list[DatasetAttachment]#

background_submit(entry_names=None, specification_names=None, compute_tag=None, compute_priority=None, find_existing=True, **kwargs)#

Adds a dataset submission internal job to the server

This internal job is the one to actually do the submission, which can take a while.

You can check the progress of the internal job using the return object.

See submit() for info on the function parameters.

Returns:

An internal job object that can be watch or used to determine the progress of the job.

Parameters:

entry_names (str | Iterable[str] | None)
specification_names (str | Iterable[str] | None)
compute_tag (str | None)
compute_priority (PriorityEnum)
find_existing (bool)

Return type:

InternalJob

cancel_records(entry_names=None, specification_names=None, *, refetch_records=False)#

Marks running, waiting, or errored records as cancelled.

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

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to cancel. If None, cancel records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to cancel. If None, cancel records for all specifications.
refetch_records (bool) – If True, refetch the cancelled records from the server.

compile_values(value_call, value_names='value', entry_names=None, specification_names=None, unpack=False)#

Compile values from records into a pandas DataFrame.

Parameters:

value_call (Callable) – Function to call on each record to extract the desired value. Must return a scalar value or a sequence of values if ‘unpack’ is set to True.
value_names (str | Sequence[str]) – Column name(s) for the extracted value(s). If a string is provided and multiple values are returned by ‘value_call’, columns are named by appending an index to this string. If a list of strings is provided, it must match the length of the sequence returned by ‘value_call’. Default is “value”.
entry_names (str | Iterable[str] | None) – Entry names to filter records. If not provided, considers all entries.
specification_names (str | Iterable[str] | None) – Specification names to filter records. If not provided, considers all specifications.
unpack (bool) – If True, unpack the sequence of values returned by ‘value_call’ into separate columns. Default is False.

Returns:

A multi-index DataFrame where each row corresponds to an entry. Each column corresponds has a top level index as a specification, and a second level index as the appropriate value name. Values are extracted from records using ‘value_call’.

Return type:

pandas.DataFrame

Raises:

ValueError – If the length of ‘value_names’ does not match the number of values returned by ‘value_call’ when ‘unpack’ is set to True.

Notes

The DataFrame is structured such that the rows are entries and columns are specifications.

2. If ‘unpack’ is True, the function assumes ‘value_call’ returns a sequence of values that need to be distributed across columns in the resulting DataFrame. ‘value_call’ should always return the same number of values for each record if unpack is True.

property computed_properties#

property contributed_values: dict[str, ContributedValues]#

copy_entries_from(source_dataset_id, entry_names=None, existing_ok=False)#

Copies entries from another dataset into this one

If entries already exist with the same name, an exception is raised.

Parameters:

source_dataset_id (int) – The ID of the dataset to copy entries from
entry_names (str | Iterable[str] | None) – Names of the entries to copy. If not provided, all entries will be copied.
existing_ok (bool) – If False and an entry already exists by that name, an exception is raised.

copy_records_from(source_dataset_id, entry_names=None, specification_names=None, existing_ok=False)#

Copies records from another dataset into this one

Entries and specifications will also be copied. If entries or specifications already exist with the same name, an exception is raised.

This does not actually fully copy records - the records will be linked to both datasets

Parameters:

source_dataset_id (int) – The ID of the dataset to copy entries from
entry_names (str | Iterable[str] | None) – Names of the entries to copy. If not provided, all entries will be copied.
specification_names (str | Iterable[str] | None) – Names of the specifications to copy. If not provided, all specifications will be copied.
existing_ok (bool) – If False and a specification or entry already exists by a supplied name, an exception is raised.

copy_specifications_from(source_dataset_id, specification_names=None)#

Copies specifications from another dataset into this one

If specifications already exist with the same name, an exception is raised.

Parameters:

source_dataset_id (int) – The ID of the dataset to copy entries from
specification_names (str | Iterable[str] | None) – Names of the specifications to copy. If not provided, all specifications will be copied.

create_view(description, provenance, status=None, include=None, exclude=None, *, include_children=True)#

Creates a view of this dataset on the server

This function will return an InternalJob which can be used to watch for completion if desired. The job will run server side without user interaction.

Note the ID field of the object if you with to retrieve this internal job later (via list_internal_jobs() or PortalClient.get_internal_job)

Parameters:

description (str) – String describing the view file
provenance (dict[str, Any]) – Dictionary with any metadata or other information about the view. Information regarding the options used to create the view will be added.
status (Iterable[RecordStatusEnum] | None) – List of statuses to include. Default is to include records with any status
include (Iterable[str] | None) – List of specific record fields to include in the export. Default is to include most fields
exclude (Iterable[str] | None) – List of specific record fields to exclude from the export. Defaults to excluding none.
include_children (bool) – Specifies whether child records associated with the main records should also be included (recursively) in the view file.

Returns:

An InternalJob object which can be used to watch for completion.

Return type:

InternalJob

property default_priority: PriorityEnum#

property default_tag: str#

delete_attachment(file_id)#

Parameters:: file_id (int)

delete_entries(names, delete_records=False)#

Deletes entries from the dataset.

Parameters:

names (str | Iterable[str]) – The name or list of names of the entries to delete.
delete_records (bool) – If True, associated records will also be deleted. Defaults to False.

Returns:

Metadata about the deletion operation.

Raises:

AssertionError – If the dataset is a view or not online.

Return type:

DeleteMetadata

delete_specification(name, delete_records=False)#

Parameters:

name (str)
delete_records (bool)

Return type:

DeleteMetadata

detailed_status()#

Returns the status of every record of the dataset individually

Unlike status(), nothing is grouped or counted - there is one entry per record. This is what to use when you need to know which entries are in a particular state.

Returns:: A list of tuples (entry name, specification name, status), in no particular order
Return type:: list[tuple[str, str, RecordStatusEnum]]

download_attachment(attachment_id, destination_path=None, overwrite=True)#

Downloads an attachment

If destination path is not given, the file will be placed in the current directory, and the filename determined by what is stored on the server.

Parameters:

attachment_id (int) – ID of the attachment to download. See the attachments property
destination_path (str | None) – Full path to the destination file (including filename)
overwrite (bool) – If True, any existing file will be overwritten

download_view(view_file_id=None, destination_path=None, overwrite=True)#

Downloads a view for this dataset

If a view_file_id is not given, the most recent view will be downloaded.

If destination path is not given, the file will be placed in the current directory, and the filename determined by what is stored on the server.

Parameters:

view_file_id (int | None) – ID of the view to download. See list_views(). If None, will download the latest view
destination_path (str | None) – Full path to the destination file (including filename)
overwrite (bool) – If True, any existing file will be overwritten

property entry_names: list[str]#

fetch_attachments()#

fetch_contributed_values()#

fetch_entries(entry_names=None, force_refetch=False)#

Fetches entry information from the remote server, storing it internally

By default, already-fetched entries will not be fetched again, unless force_refetch is True.

Parameters:

entry_names (str | Iterable[str] | None) – Names of entries to fetch. If None, fetch all entries
force_refetch (bool) – If true, fetch data from the server even if it already exists locally

Return type:

None

fetch_entry_names()#

Fetch all entry names from the remote server

These are fetched and then stored internally, and not returned.

Return type:: None

fetch_records(entry_names=None, specification_names=None, status=None, include=None, fetch_updated=True, force_refetch=False)#

Fetches record information from the remote server, storing it internally

By default, this function will only fetch records that have not been fetch previously. If force_refetch is True, then this will always fetch the records.

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to fetch. If None, fetch all entries
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to fetch. If None, fetch all specifications
status (RecordStatusEnum | Iterable[RecordStatusEnum] | None) – Fetch only records with these statuses
include (Iterable[str] | None) – Additional fields to include in the returned record
fetch_updated (bool) – Fetch any records that exist locally but have been updated on the server
force_refetch (bool) – If true, fetch data from the server even if it already exists locally

fetch_specification_names()#

Fetch all entry names from the remote server

These are fetched and then stored internally, and not returned.

Return type:: None

fetch_specifications(specification_names=None, force_refetch=False)#

Fetch specifications from the remote server, storing them internally

Parameters:

specification_names (str | Iterable[str] | None) – Names of specifications to fetch. If None, fetch all specifications
force_refetch (bool) – If true, fetch data from the server even if it already exists locally

Return type:

None

get_entry(entry_name, force_refetch=False)#

Obtain entry information

The entry will be automatically fetched from the remote server if needed.

Parameters:

entry_name (str)
force_refetch (bool)

Return type:

Any | None

get_internal_job(job_id)#

Parameters:: job_id (int)
Return type:: InternalJob

get_properties_df(properties_list, entry_names=None, specification_names=None)#

Retrieve a DataFrame populated with the specified properties from dataset records.

This function uses the provided list of property names to extract corresponding values from each record’s properties. It returns a DataFrame where rows represent each record. Each column corresponds has a top level index as a specification, and a second level index as the appropriate value name. Columns with all NaN values are dropped.

Parameters:#

properties_list: List of property names to retrieve from the records.
entry_names: Entry names to filter records. If not provided, considers all entries.
specification_names: Specification names to filter records. If not provided, considers all specifications.

Returns:#

pandas.DataFrame: A DataFrame populated with the specified properties for each record.

Parameters:

properties_list (Sequence[str])
entry_names (Sequence[str] | None)
specification_names (Sequence[str] | None)

Return type:

DataFrame

get_record(entry_name, specification_name, include=None, fetch_updated=True, force_refetch=False)#

Retrieve a calculation record associated with this dataset.

This method fetches the record from the remote server if it is not already cached locally. If the record does not exist for the specified entry and specification, it returns None.

Parameters:

entry_name (str) – The name of the entry for which the record is to be retrieved.
specification_name (str) – The name of the specification for which the record is to be retrieved.
include (Iterable[str] | None) – Additional fields to include in the fetched record, by default None.
fetch_updated (bool) – If True, fetches updated records from the server if they have been modified, by default True.
force_refetch (bool) – If True, forces a refetch of the record from the server, ignoring the local cache, by default False.

Returns:

The calculation record associated with the specified entry and specification, or None if it does not exist.

Return type:

BaseRecord | None

classmethod get_subclass(dataset_type)#

Parameters:: dataset_type (str)

property group: str#

invalidate_records(entry_names=None, specification_names=None, *, refetch_records=False)#

Marks a completed record as invalid.

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

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to invalidate. If None, invalidate records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to invalidate. If None, invalidate records for all specifications.
refetch_records (bool) – If True, refetch the invalidated records from the server.

property is_view: bool#

iterate_entries(entry_names=None, force_refetch=False)#

Iterate over all entries

This is used as a generator, and automatically fetches entries as needed

Parameters:

entry_names (str | Iterable[str] | None) – Names of entries to iterate over. If None, iterate over all entries
force_refetch (bool) – If true, fetch data from the server even if it already exists locally

iterate_records(entry_names=None, specification_names=None, status=None, include=None, fetch_updated=True, force_refetch=False)#

Parameters:

entry_names (str | Iterable[str] | None)
specification_names (str | Iterable[str] | None)
status (RecordStatusEnum | Iterable[RecordStatusEnum] | None)
include (Iterable[str] | None)
fetch_updated (bool)
force_refetch (bool)

list_internal_jobs(status=None)#

Parameters:: status (InternalJobStatusEnum | Iterable[InternalJobStatusEnum] | None)
Return type:: list[InternalJob]

list_views()#

property metadata: dict[str, Any]#

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

modify_entries(attribute_map=None, comment_map=None, overwrite_attributes=False)#

Modifies the entries in the dataset by updating their attributes or comments.

Parameters:

attribute_map (dict[str, dict[str, Any]] | None) – A dictionary mapping entry names to their updated attributes. Each entry name maps to a dictionary of attribute key-value pairs to be updated.
comment_map (dict[str, str] | None) – A dictionary mapping entry names to their updated comments.
overwrite_attributes (bool) – If True, existing attributes for the specified entries will be completely replaced by the provided attributes in attribute_map. If False, only the specified attributes will be updated, leaving others unchanged.

Raises:

AssertionError – If the dataset is a view or if the client is offline.

modify_records(entry_names=None, specification_names=None, new_compute_tag=None, new_compute_priority=None, new_comment=None, *, refetch_records=False, **kwargs)#

Modify the compute tag, compute priority, or comment of records in this dataset.

Note: compute tags are not case sensitive and will be converted to lowercase.

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to modify. If None, modify records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to modify. If None, modify records for all specifications.
new_compute_tag (str | None) – The new compute tag to assign to the records.
new_compute_priority (PriorityEnum | None) – The new compute priority to assign to the records.
new_comment (str | None) – A new comment to add to the records.
refetch_records (bool) – If True, refetch the modified records from the server.

property offline: bool#

preload_cache(view_file_id=None)#

Downloads a view file and uses it as the current cache

Parameters:: view_file_id (int | None) – ID of the view to download. See list_views(). If None, will download the latest view

print_status()#

Return type:: None

propagate_client(client, base_url_prefix)#

Propagates a client to this record to any fields within this record that need it

This may also be called from derived class propagate_client functions as well

Parameters:: base_url_prefix (str | None)

property record_count: int#

refresh_cache(entry_names=None, specification_names=None)#

Refreshes some information in the cache with information on the server

This can be used to fix some inconsistencies in the cache without deleting and starting over. For example, this can fix instances where the record attached to a given entry & specification has changed (new record id) due to renaming specifications and entries, or via remove_records followed by a submit without duplicate checking.

This will also fetch any updated records

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to fetch. If None, fetch all entries
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to fetch. If None, fetch all specifications

remove_records(entry_names, specification_names, delete_records=False)#

Parameters:

entry_names (str | Iterable[str])
specification_names (str | Iterable[str])
delete_records (bool)

Return type:

None

rename_entries(name_map)#

Renames entries in the dataset based on the provided mapping.

This method updates the names of entries both on the server and in the local cache. It ensures that the dataset is not a view and is online before proceeding with the renaming.

Parameters:: name_map (dict[str, str]) – A dictionary mapping old entry names to new entry names. Entries where the old name is the same as the new name are ignored.
Raises:: AssertionError – If the dataset is a view or is not online.

rename_specification(old_name, new_name)#

Parameters:

old_name (str)
new_name (str)

reset_records(entry_names=None, specification_names=None, *, refetch_records=False)#

Resets running or errored records to be waiting again.

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to reset. If None, reset records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to reset. If None, reset records for all specifications.
refetch_records (bool) – If True, refetch the reset records from the server.

set_default_compute_priority(new_default_compute_priority)#

Parameters:: new_default_compute_priority (PriorityEnum)

set_default_compute_tag(new_default_compute_tag)#

Parameters:: new_default_compute_tag (str)

set_default_priority(new_default_priority)#

Parameters:: new_default_priority (PriorityEnum)

set_default_tag(new_default_tag)#

Parameters:: new_default_tag (str)

set_description(new_description)#

Parameters:: new_description (str)

set_extras(new_extras)#

Parameters:: new_extras (dict[str, Any])

set_group(new_group)#

Parameters:: new_group (str)

set_metadata(new_metadata)#

Parameters:: new_metadata (dict[str, Any])

set_name(new_name)#

Parameters:: new_name (str)

set_provenance(new_provenance)#

Parameters:: new_provenance (dict[str, Any])

set_tagline(new_tagline)#

Parameters:: new_tagline (str)

set_tags(new_tags)#

Parameters:: new_tags (list[str])

set_visibility(new_visibility)#

Parameters:: new_visibility (bool)

property specification_names: list[str]#

property specifications: Mapping[str, Any]#

status()#

Returns the status of the dataset’s computations, broken down by specification

The status is computed on the server, and does not require downloading any records.

Returns:: A dictionary with specification names as keys. Each value is itself a dictionary mapping record status to the number of records of the dataset with that status. Statuses with no records are not present.
Return type:: dict[str, Any]

status_by_compute_tag()#

Returns the status of the dataset’s computations, broken down by compute tag

Only records that still have an entry in the task or service queue are counted. A record’s task is removed from the queue when it completes, so completed records do not appear here, and these counts will not sum to the counts returned by status(). In practice, this function reports the waiting, running, and errored records of the dataset - that is, the work that is still outstanding, and which compute tag it is queued under.

Returns:: A list of tuples (compute tag, status, number of records), in no particular order
Return type:: list[tuple[str, RecordStatusEnum, int]]

status_table()#

Returns the status of the dataset’s computations as a table (in a string)

Return type:: str

submit(entry_names=None, specification_names=None, compute_tag=None, compute_priority=None, find_existing=True, **kwargs)#

Create records for this dataset

This function actually populates the datasets records given the entry and specification information.

Parameters:

entry_names (str | Iterable[str] | None) – Submit only records for these entries
specification_names (str | Iterable[str] | None) – Submit only records for these specifications
compute_tag (str | None) – Use this compute tag for submissions (overrides the dataset default tag)
compute_priority (PriorityEnum | None) – Use this compute priority for submissions (overrides the dataset default priority)
find_existing (bool) – If True, the database will be searched for existing records that match the requested calculations, and new records created for those that don’t match. If False, new records will always be created.

Return type:

InsertCountsMetadata

uncancel_records(entry_names=None, specification_names=None, *, refetch_records=False)#

Undo the cancellation of records.

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to uncancel. If None, uncancel records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to uncancel. If None, uncancel records for all specifications.
refetch_records (bool) – If True, refetch the uncancelled records from the server.

uninvalidate_records(entry_names=None, specification_names=None, *, refetch_records=False)#

Undo the invalidation of records.

Parameters:

entry_names (str | Iterable[str] | None) – Names of the entries whose records to uninvalidate. If None, uninvalidate records for all entries.
specification_names (str | Iterable[str] | None) – Names of the specifications whose records to uninvalidate. If None, uninvalidate records for all specifications.
refetch_records (bool) – If True, refetch the uninvalidated records from the server.

use_view_cache(view_file_path)#

Loads a vuew for this dataset as a cache file

Parameters:: view_file_path (str) – Full path to the view file

property visibility: bool#

id#

name#

description#

tagline#

tags#

provenance#

extras#

default_compute_tag#

default_compute_priority#

creator_user#

contributed_values_#

attachments_#

auto_fetch_missing#