Merge pull request #25 from xsuite/release/v0.4.2

Release 0.4.2

Author: freddieknets

README.md

@@ -50,20 +50,22 @@ No more steps are needed as AFS can handle the I/O permissions for the Xboinc se
 
 **Important!!! If you are using EOS, you need to set the proper permissions for the Xboinc server to access your folder!!**
 
-You can do this by accessing the desired folder from the CERNBox web interface, right-clicking on the folder and selecting "Share", then adding the user `a:sixtadm` (n.b. this is the Xboinc service account) with the "Write" permission. It should look like this:
+You can do this by accessing the desired folder from the CERNBox web interface, right-clicking on the folder and selecting "Share", then adding the user `a:sixtadm` (n.b. this is the Xboinc service account) and invite as editor. It should look like this:
 
 ![Share folder with Xboinc service account](docs/img/share_folder_with_xboinc_service_account.png)
 
 After that, you can register your username with the Xboinc server by running the following command:
 
 ```python
 import xboinc as xb
-xb.register("mycernshortname", "/eos/user/m/mycernshortname/my_xboinc_folder")
+xb.register("mycernshortname", "/eos/user/m/mycernshortname/my_xboinc_folder", permissions_given=True)
 ```
 
+Note that specifying `permissions_given=True` assumes that you have already set the appropriate permissions for the Xboinc service account on the specified EOS path. Not doing so will result in a `NotImplementedError` as we currently cannot manipulate EOS ACLs directly.
+
 ## 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:
 
@@ -75,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,
@@ -107,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()

pyproject.toml

@@ -5,7 +5,7 @@
 
 [tool.poetry]
 name = "xboinc"
-version = "0.4.1"
+version = "0.4.2"
 description = "Xsuite BOINC interface"
 homepage = "https://github.com/xsuite/xboinc"
 repository = "https://github.com/xsuite/xboinc"