3.1.1.5. xboinc.retrieve
3.1.1.5.1. Classes
Class to retrieve and manage results from Xboinc simulations. |
3.1.1.5.2. Module Contents
- class ResultRetriever(user, dev_server=False, silent=False)[source]
Class to retrieve and manage results from Xboinc simulations.
This class provides functionality to retrieve, index, and manage simulation results from BOINC work units. It can untar result files, create indexes, and provide various views and statistics about completed jobs.
- _directory
Path to the directory containing results
- Type:
FsPath
Examples
>>> retriever = ResultRetriever('myuser', dev_server=True) >>> studies = retriever.get_study_list() >>> for job_name, particles in retriever.iterate_results('my_study'): ... # Process particles data ... pass
- _untar_results(path: xaux.FsPath, silent: bool = False)[source]
Untar all compressed result files in the given path.
- Parameters:
path (FsPath) – Directory path containing .tar.gz files to extract
silent (bool, optional) – If True, suppress progress bar output (default: False)
- _index_results(path: xaux.FsPath, silent: bool = False) pandas.DataFrame[source]
Index all result files in the given path and create a DataFrame.
Scans for .bin files in subdirectories and extracts metadata from filenames to create a structured index of available results.
- Parameters:
path (FsPath) – Directory path to scan for result files
silent (bool, optional) – If True, suppress progress bar output (default: False)
- Returns:
DataFrame with columns: user, study_name, job_name, wu_name, bin_file Each row represents one available result file
- Return type:
pd.DataFrame
- get_overview()[source]
Get a comprehensive overview of all available results.
- Returns:
DataFrame containing all indexed results with columns: user, study_name, job_name, wu_name, bin_file
- Return type:
pd.DataFrame
- get_study_status(study_name, verbose=False)[source]
Get detailed status information for a specific study.
Compares local results with server work units to provide comprehensive status information including completion rates and missing jobs.
- Parameters:
- Returns:
list: Job names available in results
set: Job names missing from results but present on server
- Return type:
- Raises:
ValueError – If study_name is not found in results or server work units
Warning
- UserWarning
If there are mismatches between local results and server status
- iterate_results(study_name)[source]
Iterate over all results for a specific study.
Yields tuples of job names and their corresponding particle data for all completed jobs in the specified study.
- Parameters:
study_name (str) – Name of the study to iterate over
- Yields:
tuple of (str, xpart.Particles) – Job name and corresponding particles object for each result
- Raises:
ValueError – If study_name is not found in available results
Warning
- UserWarning
If a binary file is incompatible with current Xboinc version
Examples
>>> retriever = ResultRetriever('myuser', dev_server=True) >>> for job_name, particles in retriever.iterate_results('my_study'): ... print(f"Processing job: {job_name}") ... print(f"Number of particles: {len(particles.x)}")
- clean(study_name)[source]
Clean up results for a specific study.
Removes all binary result files, empty directories, and clears the study from the internal DataFrame index.
- Parameters:
study_name (str) – Name of the study to clean up
- Raises:
ValueError – If study_name is not found in available results
Warning
This operation is irreversible. All result files for the study will be permanently deleted.
- classmethod iterate(user, study_name, dev_server=False, silent=False)[source]
Class method to directly iterate over results for a user and study.
Convenient method that creates a ResultRetriever instance and immediately starts iterating over results without requiring explicit instantiation.
- Parameters:
- Yields:
tuple of (str, xpart.Particles) – Job name and corresponding particles object for each result
Examples
>>> for job_name, particles in ResultRetriever.iterate('myuser', 'my_study', dev_server=True): ... # Process particles data ... pass
- classmethod overview(user, dev_server=False, silent=False)[source]
Class method to get an overview of results for a specific user.
- Parameters:
- Returns:
DataFrame with overview of all available results
- Return type:
pd.DataFrame
Examples
>>> overview_df = ResultRetriever.overview('myuser', dev_server=True) >>> print(overview_df.groupby('study_name').size())
- classmethod status(user, study_name, dev_server=False, silent=False, verbose=False)[source]
Class method to get status of results for a specific user and study.
- Parameters:
user (str) – The user that submitted the BOINC jobs
study_name (str) – Name of the study to check status for
dev_server (bool, optional) – Whether to use development server (default: False)
silent (bool, optional) – Whether to suppress output messages (default: True)
verbose (bool, optional) – If True, print detailed job lists (default: False)
- Returns:
list: Job names available in results
set: Job names missing from results but present on server
- Return type:
Examples
>>> available, missing = ResultRetriever.status('myuser', 'my_study', dev_server=True) >>> print(f"Available jobs: {len(available)}, Missing jobs: {len(missing)}")
- classmethod study_list(user, dev_server=False, silent=False)[source]
Class method to get a list of all studies for a specific user.
- Parameters:
- Returns:
Sorted list of unique study names found in the results
- Return type:
Examples
>>> studies = ResultRetriever.study_list('myuser', dev_server=True) >>> print(studies)