Work in progress

docs/_config.yml

@@ -1,6 +1,6 @@
 title: " "
 author: The TOAST Development Team
-copyright: 2015-2022
+copyright: 2015-2023
 logo: toast_logo_txt_small.png
 
 # Force re-execution of notebooks on each build.
@@ -21,7 +21,7 @@ latex:
 repository:
   url: https://github.com/hpc4cmb/toast  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
-  branch: main  # Which branch of the repository should be used when creating links (optional)
+  branch: toast3  # Which branch of the repository should be used when creating links (optional)
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository

docs/_toc.yml

@@ -7,6 +7,7 @@ chapters:
   - file: install_user
   - file: install_dev
   - file: install_nersc
+  - file: install_test
 - file: interactive
 # - file: quickstart
 - file: data_model

docs/install.md

@@ -1,39 +1,6 @@
 # Installation
 
 TOAST is written in C++ and python3 and depends on several commonly available packages.
-It also has some optional functionality that is only enabled if additional external
+It also has optional functionality that is only enabled if additional external
 packages are available.  The best installation method will depend on your specific
 needs.  We try to clarify the different options in the following sections.
-
-
-(install:test)=
-## Testing the Installation
-
-After installation (regardless of method), you can run both the compiled and
-python unit tests.  These tests will create an output directory named
-`toast_test_output` in your current working directory:
-
-```{code-block} console
-python -c "import toast.tests; toast.tests.run()"
-```
-
-If you have installed the `mpi4py` package, then you can also run the unit tests with
-MPI enabled.  For example:
-
-```{code-block} console
-export OMP_NUM_THREADS=2
-mpirun -np 2 python -c "import toast.tests; toast.tests.run()"
-```
-
-```{important}
-You should use whatever MPI launcher is appropriate for your system (e.g.  `mpirun`,
-`mpiexec`, `srun`, etc).  In general, be sure to set the `OMP_NUM_THREADS` environment
-variable so that the number of MPI processes times this number of threads is not greater
-than the number of physical CPU cores.
-```
-
-The runtime configuration of toast can also be checked with an included script:
-
-```{code-block} bash
-toast_env
-```

docs/install_user.md

@@ -11,8 +11,8 @@ If you want to use a pre-installed version of TOAST at NERSC,
 
 ## Pip Binary Wheels
 
-If you already have a newer Python3 (\>= 3.7), then you can install pre-built TOAST
-packages from PyPI.  You should always use virtualenv or similar tools to manage your
+If you already have a newer Python3 (\>= 3.8), then you can install pre-built TOAST
+packages from PyPI.  You should **always** use virtualenv or similar tools to manage your
 python environments rather than pip-installing packages as root.
 
 On Debian / Ubuntu Linux, you should install these minimal packages:
@@ -33,7 +33,7 @@ scl enable rh-python38 bash
 ```
 
 On MacOS, you can use homebrew or macports to install a recent python3.
-Now verify that your python is at least 3.7:
+Now verify that your python is at least 3.8:
 
 ```{code-block} bash
 python3 --version
@@ -64,36 +64,13 @@ Next, use pip to install toast and its requirements:
 pip install toast
 ```
 
-(install:user:mpi)=
-### Enabling MPI Support
-
-At this point you have toast installed and you can use it from serial scripts and
-notebooks.  If you want to enable effective parallelism with toast (useful if your
-computer has many cores), then you need to install the `mpi4py` package.  This package
-requires MPI compilers (usually MPICH or OpenMPI).  Your system may already have some
-MPI compilers installed- try this:
-
-```{code-block} bash
-which mpicc
-mpicc -show
-```
-
-If the mpicc command is not found, you should use your OS package manager to install the
-development packages for MPICH or OpenMPI.  Now you can install mpi4py:
-
-```{code-block} bash
-pip install mpi4py
-```
-
-For more details about custom installation options for mpi4py, read the [documentation
-for that package](https://mpi4py.readthedocs.io/en/stable/install.html).  After
-installation, [you should run the unit tests](install:test)
-
 (install:user:conda)=
 ## Conda Packages
 
-If you already use (or would like to use) the conda python stack, then you can install
-TOAST and all of its optional dependencies with the conda package manager.  The
+The conda package manager and conda-forge ecosystem provides thousands of high quality software packages (both python and compiled tools) that are built with a consistent set of compilers and provide a way of managing python environments independent from the operating system environment.
+
+You can install
+TOAST and many of its optional dependencies with the conda package manager.  The
 conda-forge ecosystem allows us to create packages that are built consistently with all
 their dependencies.  When we talk about the `base` conda environment (previously called
 the "root" environment), this is the initial environment loaded when the conda shell
@@ -103,7 +80,7 @@ across all the different projects you might be working on.  It also creates a
 maintenance nightmare when you need to update packages.  In this section we walk through
 creating a conda *environment* to use for TOAST / CMB analysis work.
 
-By keeping a minimal base and using environments for all other work, it is trivial to
+By keeping a minimal base and using other environments for all other work, it is trivial to
 update the conda tool itself and the other essential packages in base.  If one of your
 working environments becomes horribly out of date or broken, just delete it and make a
 new one.
@@ -191,6 +168,34 @@ conda deactivate
 As always, after installation, [you should run the unit tests](install:test).
 
 
+
+(install:user:mpi)=
+### Enabling MPI Support
+
+At this point you have toast installed and you can use it from serial scripts and
+notebooks.  If you want to enable effective parallelism with toast (useful if your
+computer has many cores), then you need to install the `mpi4py` package.  This package
+requires MPI compilers (usually MPICH or OpenMPI).  Your system may already have some
+MPI compilers installed- try this:
+
+```{code-block} bash
+which mpicc
+mpicc -show
+```
+
+If the mpicc command is not found, you should use your OS package manager to install the
+development packages for MPICH or OpenMPI.  Now you can install mpi4py:
+
+```{code-block} bash
+pip install mpi4py
+```
+
+For more details about custom installation options for mpi4py, read the [documentation
+for that package](https://mpi4py.readthedocs.io/en/stable/install.html).  After
+installation, [you should run the unit tests](install:test)
+
+
+
 ## Something Else
 
 If you have a custom install situation that is not met by the above solutions, then you

docs/interactive.ipynb

@@ -232,7 +232,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,

docs/intro.md

@@ -19,10 +19,10 @@ The TOAST framework contains:
 - Basic classes for performing I/O in a limited set of formats
 - Well-defined interfaces for adding custom I/O classes and processing operators
 
-The highest-level control of the workflow is done by the user, often by writing a small
-Python script or notebook (some examples are included).  Such scripts make use of TOAST
-functions for distributing data and then call built-in or custom operators to process
-the timestream data.
+The highest-level control of the workflow is done by the user, often by writing
+a small Python script or notebook (some examples are included). Such scripts
+make use of TOAST functionality for distributing data and then call built-in or
+custom operators to simulate and / or process the timestream data.
 
 The Time-Ordered Astrophysics Scalable Tools (TOAST) package is a software framework
 designed for simulation and reduction of data from telescope receivers which acquire

docs/toast_docs.py

@@ -195,9 +195,6 @@ def fake_ground_observing_smallpatch(
 
     # Create a schedule.
 
-    # FIXME: change this once the ground scheduler supports in-memory creation of the
-    # schedule.
-
     schedule = None
 
     if mpicomm is None or mpicomm.rank == 0:
@@ -221,9 +218,9 @@ def fake_ground_observing_smallpatch(
                 "--patch",
                 "small_patch,1,40,-40,44,-44",
                 "--start",
-                "2020-01-01 00:00:00",
+                "2025-01-01 00:00:00",
                 "--stop",
-                "2020-01-01 06:00:00",
+                "2025-01-01 06:00:00",
                 "--out",
                 sch_file,
             ]
@@ -473,11 +470,6 @@ def simulate_ground_data(data, fig=None):
     toast.ops.Combine(first="atmosphere", second="signal", result="signal", op="add").apply(data)
     toast.ops.Combine(first="DC", second="signal", result="signal", op="add").apply(data)
 
-    # FIXME: this is a hack- we should have the scan map operator use units and
-    # set the units when we create the detdata above.
-    for ob in data.obs:
-        ob.detdata["signal"]._units = u.K
-
     # Delete data objects used in the simulation.
     del data[build_dist.pixel_dist]
     toast.ops.Delete(

tutorial/01_Introduction/intro.ipynb

@@ -1111,7 +1111,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.10.0"
   }
  },
  "nbformat": 4,