[Documentation] Add FAQ section explaining cores, threads_per_core and max_workers

docs/trouble_shooting.md

@@ -52,8 +52,45 @@ The `coverage combine` command merges the data from the main process and subproc
 
 ## Python Version 
 Executorlib supports all current Python version ranging from 3.9 to 3.13. Still some of the dependencies and especially 
-the [flux](http://flux-framework.org) job scheduler are currently limited to Python 3.12 and below. Consequently for high
-performance computing installations Python 3.12 is the recommended Python verion. 
+the [flux](http://flux-framework.org) job scheduler are currently limited to Python 3.13 and below. Consequently for high
+performance computing installations Python 3.13 is the recommended Python verion. 
+
+## Cores, Threads per Core and Maximum Workers
+A common point of confusion is the difference between the `cores`, `threads_per_core` and `max_workers` (or `max_cores`)
+parameters, as they all control how many compute resources executorlib uses, but on different levels:
+
+* `max_workers` / `max_cores` are arguments of the `Executor` itself. They define the *total* number of compute cores
+  the executor is allowed to use in parallel across all submitted function calls - essentially the size of the resource
+  pool or allocation that all tasks share. `max_workers` exists for backwards compatibility with the
+  [Executor interface](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Executor) of the
+  Python standard library, while `max_cores` is the recommended way to express the same limit, as it makes clear that the
+  limit refers to the number of compute cores. Setting either is optional - when neither is provided executorlib uses the
+  number of cores available on the machine.
+* `cores` is an entry of the `resource_dict` and is defined *per function call*. It specifies how many Python processes
+  executorlib starts for a single task. These processes are connected via
+  [mpi4py](https://mpi4py.readthedocs.io) and together form one MPI application. Consequently, `cores` is primarily
+  intended for functions implemented with [mpi4py](https://mpi4py.readthedocs.io), where the same Python function is
+  executed once per MPI rank. For a typical serial Python function, increasing `cores` does **not** provide additional
+  parallelism. Instead, executorlib launches multiple copies of the function, which usually wastes resources and can
+  lead to incorrect behavior. Unless you are using MPI through [mpi4py](https://mpi4py.readthedocs.io), `cores`
+  should generally be left at its default value of `1`.
+* `threads_per_core` is also an entry of the `resource_dict` and defined *per function call*. In contrast to `cores`,
+  executorlib starts only a single Python process for the task and reserves the requested resources for that process.
+  The number of reserved cores is communicated through environment variables such as `OMP_NUM_THREADS`. This parameter
+  should be used whenever the Python function itself is executed only once, but internally uses multiple cores. Common
+  examples include thread-parallel libraries such as NumPy, BLAS, MKL or OpenMP-enabled code, as well as Python
+  functions which launch external applications. In the latter case, executorlib starts a single Python process, which
+  then launches the external application. Whether that external application internally uses OpenMP, MPI or a hybrid
+  MPI/OpenMP parallelization strategy is transparent to executorlib. This functionality is demonstrated in the Quantum
+  ESPRESSO application example.
+
+A useful rule of thumb is:
+
+* Use `cores` when executorlib should start multiple Python processes which together form an MPI application via
+  `mpi4py`.
+* Use `threads_per_core` when executorlib should start the Python function only once and reserve multiple cores for it
+  or for an external application launched by it.
+* Use `max_cores` to limit how many resources all submitted tasks may consume collectively.
 
 ## Resource Dictionary
 The resource dictionary parameter `resource_dict` can contain one or more of the following options: