Repository: openmc-dev/openmc

Issue:
mismatch between max_tracks in python and c++
the ```settings.max_tracks``` defaults to None in the python layer

https://github.com/openmc-dev/openmc/blob/e27c3b4a5bb6ac97ffe1f01a06b96a6d65d83471/openmc/settings.py#L298

 and the docs state **all** particles will be written if run in tracks mode

https://github.com/openmc-dev/openmc/blob/e27c3b4a5bb6ac97ffe1f01a06b96a6d65d83471/openmc/model/model.py#L519-L520

https://github.com/openmc-dev/openmc/blob/e27c3b4a5bb6ac97ffe1f01a06b96a6d65d83471/openmc/settings.py#L108-L109

However it defaults to 1000 in the C++ layer.

https://github.com/openmc-dev/openmc/blob/e27c3b4a5bb6ac97ffe1f01a06b96a6d65d83471/src/settings.cpp#L98

This could result in a user not realizing that ```max_tracks``` must be set to a larger number if more than 1000 particles are needed

Thanks very much to @zoranpesic for reporting this.

I am happy to put in a PR to clear this up if this issue gets a :+1: 

I would recommend 
 - we set the default ```Settings.max_tracks``` to 1000 on the python side to match the c++ side
 - we remove the word all from the doc string of model tracks to say ```Write tracks for particles. Defaults to False.```


Discussion:
Setting `max_tracks` to 1000 on the Python side will result in it _always_ getting written to settings.xml, which is undesirable in my opinion. I think we should just update our documentation to reflect the default of 1000 on the C++ side.
I had a go at replacing this doc string ```Write tracks for all particles. Defaults to False. ``` but it is not very elegant

```
Enables the writing of particles tracks. The number of particle tracks written to tracks.h5 is limited by
whichever is smaller between the number of particles set by Settings.max_tracks and 1000. Defaults to False. 
```
> limited by whichever is smaller between the number of particles set by Settings.max_tracks and 1000

If `max_tracks` is set by the user, that value will always be used. The default of 1000 only applies if `max_tracks` hasn't been specified and a user enables particle track writing.
Perhaps edging closer

```
Enables the writing of particles tracks. The number of particle tracks written to 
tracks.h5 is limited to 1000 unless Settings.max_tracks is set. Defaults to False. 
```
@shimwell Since you're on a PR spree, do you want to submit a PR changing the description of the `tracks` argument in `Model.run`, `openmc.run`, etc.? :smile: 

Resolving patch:
diff --git a/openmc/executor.py b/openmc/executor.py
--- a/openmc/executor.py
+++ b/openmc/executor.py
@@ -31,7 +31,9 @@ def _process_CLI_arguments(volume=False, geometry_debug=False, particles=None,
         to the number of hardware threads available (or a value set by the
         :envvar:`OMP_NUM_THREADS` environment variable).
     tracks : bool, optional
-        Write tracks for all particles. Defaults to False.
+        Enables the writing of particles tracks. The number of particle
+        tracks written to tracks.h5 is limited to 1000 unless
+        Settings.max_tracks is set. Defaults to False.
     event_based : None or bool, optional
         Turns on event-based parallelism if True. If None, the value in
         the Settings will be used.
@@ -245,7 +247,9 @@ def run(particles=None, threads=None, geometry_debug=False,
     restart_file : str, optional
         Path to restart file to use
     tracks : bool, optional
-        Write tracks for all particles. Defaults to False.
+        Enables the writing of particles tracks. The number of particle
+        tracks written to tracks.h5 is limited to 1000 unless
+        Settings.max_tracks is set. Defaults to False.
     output : bool
         Capture OpenMC output from standard out
     cwd : str, optional
diff --git a/openmc/model/model.py b/openmc/model/model.py
--- a/openmc/model/model.py
+++ b/openmc/model/model.py
@@ -256,7 +256,9 @@ def init_lib(self, threads=None, geometry_debug=False, restart_file=None,
         restart_file : str, optional
             Path to restart file to use
         tracks : bool, optional
-            Write tracks for all particles. Defaults to False.
+            Enables the writing of particles tracks. The number of particle
+            tracks written to tracks.h5 is limited to 1000 unless
+            Settings.max_tracks is set. Defaults to False.
         output : bool
             Capture OpenMC output from standard out
         event_based : None or bool, optional
@@ -517,7 +519,9 @@ def run(self, particles=None, threads=None, geometry_debug=False,
         restart_file : str, optional
             Path to restart file to use
         tracks : bool, optional
-            Write tracks for all particles. Defaults to False.
+            Enables the writing of particles tracks. The number of particle
+            tracks written to tracks.h5 is limited to 1000 unless
+            Settings.max_tracks is set. Defaults to False.
         output : bool, optional
             Capture OpenMC output from standard out
         cwd : str, optional


Test patch: