updated docs for parallelization

Author: mitzimorris

docsrc/hello_world.rst

@@ -61,6 +61,8 @@ The function :func:`~cmdstan_path` returns the value of this environment variabl
     # inspect model object 
     print(model)
 
+    # inspect compiled model
+    print(model.exe_info)
             
 Data inputs
 ^^^^^^^^^^^
@@ -184,6 +186,31 @@ to a specified directory.
     fit.save_csvfiles(dir='some/path')
 
 
+Parallelization
+^^^^^^^^^^^^^^^
+
+The Stan language
+`reduce_sum <https://mc-stan.org/docs/stan-users-guide/reduce-sum.html>`__
+function provides within-chain parallelization.
+For models which require computing the sum of a number of independent function evaluations,
+e.g., when evaluating a number of conditionally independent terms in a log-likelihood,
+the ``reduce_sum`` function is used to parallelize this computation.
+
+As of version CmdStan 2.28, it is possible to run the
+NUTS-HMC sampler on
+multiple chains from within a single executable using threads.
+This has the potential to speed up sampling.  It also
+reduces the overall memory footprint required for sampling as
+all chains share the same copy of data.the input data.
+When using within-chain parallelization all chains started within a single executable can share all the available threads and once a chain finishes the threads will be reused.
+
+Both within-chain and cross-chain parallelization use the
+Intel Threading Building Blocks (TBB) library.
+In order to do either, the Stan model must be compiled with
+C++ compiler flag ``STAN_THREADS``.  While any value can be used,
+we recommend the value ``TRUE``.
+
+
 Progress bar
 ^^^^^^^^^^^^
 
@@ -201,9 +228,8 @@ To suppress the progress bar, specify argument ``show_progress=False``.
 
     fit = model.sample(data=data_file, show_progress=False)
 
-To see the CmdStan console outputs instead, specify ``show_console=True``.
+To see the CmdStan console outputs instead of progress bars, specify ``show_console=True``.
 
- 
 .. ipython:: python
     :verbatim:
 

docsrc/workflow.rst

@@ -87,25 +87,22 @@ specify options for each compilation step.
 Options are specified as a Python dictionary mapping
 compiler option names to appropriate values.
 
-To use Stan's 
-`parallelization <https://mc-stan.org/docs/cmdstan-guide/parallelization.html>`__
-features, Stan programs must be compiled with the appropriate C++ compiler flags.
-If you are running GPU hardware and wish to use the OpenCL framework to speed up matrix operations,
-you must set the C++ compiler flag **STAN_OPENCL**.
-For high-level within-chain parallelization using the Stan language `reduce_sum` function,
-it's necessary to set the C++ compiler flag **STAN_THREADS**.  While any value can be used,
-we recommend the value ``True``.
-
-For example, given Stan program named 'proc_parallel.stan', you can take
-advantage of both kinds of parallelization by specifying the compiler options when instantiating
-the model:
+In order parallelize within-chain computations using the
+Stan language ``reduce_sum`` function, or to parallelize
+running the NUTS-HMC sampler across chains,
+the Stan model must be compiled with
+C++ compiler flag **STAN_THREADS**.
+While any value can be used,
+we recommend the value ``True``, e.g.:
+
 
 .. code-block:: python
 
-    proc_parallel_model = CmdStanModel(
-        stan_file='proc_parallel.stan',
-        cpp_options={"STAN_THREADS": True, "STAN_OPENCL": True},
-    )
+    import os
+    from cmdstanpy import CmdStanModel
+
+    my_stanfile = os.path.join('.', 'my_model.stan')
+    my_model = CmdStanModel(stan_file=my_stanfile, cpp_options={'STAN_THREADS':'true'})
 
 
 Assemble input and initialization data