Renamed JobManager as JobSubmitter and ResultRetriever as JobRetriever, and updated examples.

Author: freddieknets

README.md

@@ -65,7 +65,7 @@ Note that specifying `permissions_given=True` assumes that you have already set
 
 ## Submit a job
 
-To submit a job to the LHC@home project, you can use the `JobManager` class from the `xboinc` package. With `JobManager`, you can create a study, which will contain a set of jobs to be executed. Ideally, you should create a study for a single line to track, with multiple jobs for spreading the number of particles to track. However, it is also possible to create a study with multiple lines.
+To submit a job to the LHC@home project, you can use the `JobSubmitter` class from the `xboinc` package. With `JobSubmitter`, you can create a study, which will contain a set of jobs to be executed. Ideally, you should create a study for a single line to track, with multiple jobs for spreading the number of particles to track. However, it is also possible to create a study with multiple lines.
 
 Here is an example of how to submit a job:
 
@@ -77,7 +77,7 @@ import xboinc as xb
 line = xt.Line.from_json("path/to/your/line.json")
 
 # create a job manager
-job_manager = xb.JobManager(
+job_manager = xb.JobSubmitter(
     user="mycernshortname",
     study_name="a_relevant_study_name",
     line=line,
@@ -109,12 +109,12 @@ Note that the jobs will be executed on a single CPU core from a volunteer comput
 
 ## Retrieve the results
 
-When the jobs are completed, the Xboinc server will store the results in your allocated folder in compressed tar files. You can decompress and explore them by using the `ResultRetriever` class from the `xboinc` package. The simplest way to do that is:
+When the jobs are completed, the Xboinc server will store the results in your allocated folder in compressed tar files. You can decompress and explore them by using the `JobRetriever` class from the `xboinc` package. The simplest way to do that is:
 
 ```python
 import xboinc as xb
 
-for job_name, result_particles in xb.ResultRetriever.iterate("mycernshortname", "a_relevant_study_name", dev_server=True):
+for job_name, result_particles in xb.JobRetriever.iterate("mycernshortname", "a_relevant_study_name", dev_server=True):
     print(f"Job {job_name} completed with particles: {result_particles.to_dict()}")
 
 ```

examples/results.py

@@ -1,13 +1,13 @@
 # copyright ############################### #
 # This file is part of the Xboinc Package.  #
-# Copyright (c) CERN, 2024.                 #
+# Copyright (c) CERN, 2025.                 #
 ########################################### #
 
 import xboinc as xb
 
 list_of_succeeded_jobs = []
 user='sixtadm'
 study_name='example_study'
-for new_particles, jobinfo in xb.RetrieveJobs(user=user, study_name=study_name):
-    print(jobinfo)
+for jobname, new_particles in xb.JobRetriever(user=user, study_name=study_name, dev_server=True):
+    print(jobname)
     print(f"Particles: {new_particles.at_turn}")

examples/submission.py

@@ -25,8 +25,9 @@
                                 y_norm=np.random.normal(0, 10, num_part_per_job*num_jobs),
                                 nemitt_x=3.5e-6, nemitt_y=3.5e-6)
 
+# Do the submission
 study_name = "example_study"
-jobs = xb.SubmitJobs(user=user, study_name=study_name, line=line, dev_server=True)
+jobs = xb.JobSubmitter(user=user, study_name=study_name, line=line, dev_server=True)
 prev = time.time()
 for i in range(num_jobs):
     # select subgroup of particles
@@ -40,3 +41,10 @@
         now = time.time() ; print(f"{i+1}/{num_jobs}  ({now-prev:.4}s)"); prev = now
 jobs.submit()
 
+
+# Alternatively, instead of manually looping over each job, you can use the `slice_and_add` method to create n jobs:
+study_name = "example_study_2"
+jobs = xb.JobSubmitter(user=user, study_name=study_name, line=line, dev_server=True)
+jobs.slice_and_add(base_job_name='job', num_turns=num_turns, particles=all_part,
+                   checkpoint_every=checkpoint_every)
+jobs.submit()

tests/test_03_submission_and_retrieval.py

@@ -165,7 +165,7 @@ def submit_study_jobs(
     line: xt.Line,
     x_sigma: float = 0.01,
     y_sigma: float = 0.003,
-) -> xb.JobManager:
+) -> xb.JobSubmitter:
     """
     Submit a complete study with multiple jobs.
 
@@ -182,10 +182,10 @@ def submit_study_jobs(
 
     Returns
     -------
-    xb.JobManager
+    xb.JobSubmitter
         The job manager used for submission.
     """
-    jobs = xb.JobManager(user=user, study_name=study_name, line=line, dev_server=True)
+    jobs = xb.JobSubmitter(user=user, study_name=study_name, line=line, dev_server=True)
 
     for i in range(TestConfig.num_jobs()):
         particles = create_random_particles(
@@ -299,7 +299,7 @@ def test_submission(monkeypatch, registered_user, clean_directories):
     )
 
     # Test that adding jobs after submission fails
-    jobs = xb.JobManager(
+    jobs = xb.JobSubmitter(
         registered_user, f"{TestConfig.STUDY_NAME}_temp", line=line, dev_server=True
     )
     jobs.submit()
@@ -324,7 +324,7 @@ def test_submission(monkeypatch, registered_user, clean_directories):
 
     # Test that production server raises NotImplementedError
     with pytest.raises(NotImplementedError):
-        xb.JobManager(registered_user, f"{TestConfig.STUDY_NAME}_3", line=line)
+        xb.JobSubmitter(registered_user, f"{TestConfig.STUDY_NAME}_3", line=line)
 
     # Validate submitted tar files
     tar_files = list(
@@ -358,7 +358,7 @@ def test_retrieval(registered_user):
         shutil.copy(tar_file, output_dir)
 
     # Iterate through jobs and validate results
-    for _, result_particles in xb.ResultRetriever.iterate(
+    for _, result_particles in xb.JobRetriever.iterate(
         "testuser", "example_study_fourth", dev_server=True
     ):
         assert len(result_particles.x) == 100

xboinc/__init__.py

@@ -7,14 +7,14 @@
 from .executable import generate_executable, generate_executable_source
 from .general import __version__, __xsuite__versions__, _pkg_root
 from .register import deregister, register
-from .retrieve import ResultRetriever
+from .retrieve import JobRetriever
 from .simulation_io import (
     XbInput,
     XbState,
     app_version,
     app_version_int,
     assert_versions,
 )
-from .submit import JobManager
+from .submit import JobSubmitter
 
 _skip_xsuite_version_check = False

xboinc/retrieve.py

@@ -17,7 +17,7 @@
 from .user import get_directory, get_domain
 
 
-class ResultRetriever:
+class JobRetriever:
     """
     Class to retrieve and manage results from Xboinc simulations.
 
@@ -40,7 +40,7 @@ class ResultRetriever:
 
     Examples
     --------
-    >>> retriever = ResultRetriever('myuser', dev_server=True)
+    >>> retriever = JobRetriever('myuser', dev_server=True)
     >>> studies = retriever.get_study_list()
     >>> for job_name, particles in retriever.iterate_results('my_study'):
     ...     # Process particles data
@@ -50,7 +50,7 @@ class ResultRetriever:
     def _untar_results(self, path: FsPath, silent: bool = False):
         """
         Untar all compressed result files in the given path.
-        
+
         Parameters
         ----------
         path : FsPath
@@ -116,7 +116,7 @@ def _index_results(self, path: FsPath, silent: bool = False) -> pd.DataFrame:
 
     def __init__(self, user, dev_server=False, silent=False):
         """
-        Initialize the ResultRetriever for a specific user.
+        Initialize the JobRetriever for a specific user.
 
         Parameters
         ----------
@@ -137,7 +137,7 @@ def __init__(self, user, dev_server=False, silent=False):
 
         Examples
         --------
-        >>> retriever = ResultRetriever('myuser', dev_server=True, silent=True)
+        >>> retriever = JobRetriever('myuser', dev_server=True, silent=True)
         >>> overview = retriever.get_overview()
         """
 
@@ -314,7 +314,7 @@ def iterate_results(self, study_name):
 
         Examples
         --------
-        >>> retriever = ResultRetriever('myuser', dev_server=True)
+        >>> retriever = JobRetriever('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)}")
@@ -375,7 +375,7 @@ def iterate(cls, user, study_name, dev_server=False, silent=False):
         """
         Class method to directly iterate over results for a user and study.
 
-        Convenient method that creates a ResultRetriever instance and immediately
+        Convenient method that creates a JobRetriever instance and immediately
         starts iterating over results without requiring explicit instantiation.
 
         Parameters
@@ -396,7 +396,7 @@ def iterate(cls, user, study_name, dev_server=False, silent=False):
 
         Examples
         --------
-        >>> for job_name, particles in ResultRetriever.iterate('myuser', 'my_study', dev_server=True):
+        >>> for job_name, particles in JobRetriever.iterate('myuser', 'my_study', dev_server=True):
         ...     # Process particles data
         ...     pass
         """
@@ -424,7 +424,7 @@ def overview(cls, user, dev_server=False, silent=False):
 
         Examples
         --------
-        >>> overview_df = ResultRetriever.overview('myuser', dev_server=True)
+        >>> overview_df = JobRetriever.overview('myuser', dev_server=True)
         >>> print(overview_df.groupby('study_name').size())
         """
         instance = cls(user, dev_server=dev_server, silent=silent)
@@ -456,7 +456,7 @@ def status(cls, user, study_name, dev_server=False, silent=False, verbose=False)
 
         Examples
         --------
-        >>> available, missing = ResultRetriever.status('myuser', 'my_study', dev_server=True)
+        >>> available, missing = JobRetriever.status('myuser', 'my_study', dev_server=True)
         >>> print(f"Available jobs: {len(available)}, Missing jobs: {len(missing)}")
         """
         instance = cls(user, dev_server=dev_server, silent=silent)
@@ -483,7 +483,7 @@ def study_list(cls, user, dev_server=False, silent=False):
 
         Examples
         --------
-        >>> studies = ResultRetriever.study_list('myuser', dev_server=True)
+        >>> studies = JobRetriever.study_list('myuser', dev_server=True)
         >>> print(studies)
         """
         instance = cls(user, dev_server=dev_server, silent=silent)