merge doc changes from master

activitysim/abm/models/utility_steps.py

@@ -1,4 +1,4 @@
-# aFreight
+# ActivitySim
 # See full license in LICENSE.txt.
 
 import logging
@@ -15,6 +15,14 @@
 
 @inject.step()
 def write_data_dictionary(output_dir):
+    """
+    Write table_name, number of rows, columns, and bytes for each checkpointed table
+
+    Parameters
+    ----------
+    output_dir: str
+
+    """
     pd.options.display.max_columns = 500
     pd.options.display.max_rows = 100
 

bin/build_docs.sh

@@ -33,9 +33,9 @@ if [ "$TRAVIS_REPO_SLUG" == "ActivitySim/activitysim" ] && \
         [ "$TRAVIS_PULL_REQUEST" == "false" ] && \
         [ "$ACTUAL_TRAVIS_JOB_NUMBER" == "1" ]; then
 
-#        echo "Installing dependencies"
-#        conda install --yes --quiet sphinx numpydoc
-#        pip install sphinx_rtd_theme
+        # assume these are installed already
+        # echo "Installing dependencies"
+        # pip install sphinx numpydoc sphinx_rtd_theme
 
         echo "Building docs"
         cd docs

docs/_static/theme_overrides.css

@@ -0,0 +1,10 @@
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}

docs/abmexample.rst

@@ -79,14 +79,14 @@ is the main settings file for the model run.  This file includes:
 Chunk size
 ~~~~~~~~~~
 
-The ``chunk_size`` is the number of doubles in a chunk of the choosers table.  It is the number of rows 
-times the number of columns and it needs to be set to a value that efficiently processes the table with 
-the available RAM.  For example, a chunk size of 1,000,000 could be 100,000 households with 10 attribute 
-columns.  Setting the chunk size too high will run into memory errors such as ``OverflowError: Python int 
+The ``chunk_size`` is the number of doubles in a chunk of the choosers table.  It is approximately the number 
+of rows times the number of columns and it needs to be set to a value that efficiently processes the table with 
+the available RAM.  For example, a chunk size of 1,000,000 could be 100,000 households with 10 columns.  Setting 
+the chunk size too high will run into memory errors such as ``OverflowError: Python int 
 too large to convert to C long.`` Setting the chunk size too low may result in smaller than optimal vector
 lengths, which may waste runtime.  The chunk size is dependent on the size of the population, the complexity 
 of the utility expressions, the amount of RAM on the machine, and other problem specific dimensions.  Thus, 
-it needs to be set via experimentation.  
+it needs to be set via experimentation.
 
 Logging
 ~~~~~~~

docs/conf.py

@@ -17,6 +17,14 @@
 
 import sphinx_rtd_theme
 
+# -- Get Package Version --------------------------------------------------
+with open("../setup.py") as file:
+    lines = file.readlines()
+    for l in lines:
+        if "version" in l:
+            VERSION = l.replace("version='", "").replace("',", "").replace(" ", "")
+            print("package version: " + VERSION)
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -60,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.5.1'
+version = VERSION
 # The full version, including alpha/beta/rc tags.
-release = '0.5.1'
+release = VERSION
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -136,7 +144,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -265,3 +273,12 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+# -- Table width fix for Read the Docs Sphinx theme -----------------------
+html_static_path = ['_static']
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+        ],
+     }

docs/core.rst

@@ -318,6 +318,19 @@ API
 Helpers
 -------
 
+.. _chunk_in_detail:
+
+Chunk
+~~~~~
+
+Chunking management
+
+API
+^^^
+
+.. automodule:: activitysim.core.chunk
+   :members:
+
 Utilities
 ~~~~~~~~~
 

docs/development.rst

@@ -99,6 +99,19 @@ which `assert` is failing, you can work your way back through the code that crea
 order to update it.  After updating the test targets, re-run the tests to confirm the new code passes all 
 the tests.
 
+Profiling
+---------
+
+A good way to profile ActivitySim model runs is to use `snakeviz <https://jiffyclub.github.io/snakeviz/>`__.  
+To do so, first install snakeviz and then run ActivitySim with the Python profiler (cProfile) to create 
+a profiler file.  Then run snakeviz on the profiler file to interactively explore the component runtimes.
+
+::
+
+    pip install snakeviz
+    python -m cProfile -o asim.prof simulation.py
+    snakeviz asim.prof
+
 Documentation
 -------------
 

docs/gettingstarted.rst

@@ -52,8 +52,8 @@ server. To do so, create a ``.condarc`` file in your Anaconda installation folde
 ::
     
     proxy_servers:
-      http: http://proxynew.odot.state.or.us:8080
-      https: https://proxynew.odot.state.or.us:8080
+      http: http://myproxy.org:8080
+      https: https://myproxy.org:8080
     ssl_verify: false
 
 This will create a new conda environment named ``asimtest`` and set it as the 
@@ -101,7 +101,7 @@ your proxy server when downloading packages.  For example:
 
 ::
     
-    pip install --trusted-host pypi.python.org --proxy=proxynew.odot.state.or.us:8080  cytoolz
+    pip install --trusted-host pypi.python.org --proxy=myproxy.org:8080  cytoolz
 
 ActivitySim
 ~~~~~~~~~~~
@@ -142,6 +142,19 @@ done with ``pip uninstall activitysim``.
 
 .. _expressions_in_detail :
 
+Hardware
+--------
+
+The computing hardware required to run an ActivitySim-based model generally depends on:
+
+* the number of households to be simulated
+* the number and size of network skims (i.e. the number of model zones (for each zone system if applicable))
+* the desired runtimes
+
+ActivitySim requires a substantial amount of RAM since it stores data in-memory in order to minimize runtimes.
+For example, the example model is tested on a Windows server with 256GB of RAM and 48 threads.  ActivitySim
+is NOT currently multi-threaded/processed, but this improvement is in the development roadmap.
+
 Expressions
 -----------
 

docs/howitworks.rst

@@ -92,7 +92,7 @@ by implementation.
   from activitysim.core import pipeline
   import extensions
 
-The ``extensions`` are stored in the example folder\extensions and include an init.py class that 
+The ``extensions`` are stored in the example folder extensions folder and include an init.py class that 
 loads each table extension.  In the example, the household, landuse, and person tables all have extensions.
 For example, the landuse extension adds a new column to the land use table called ``total_households``, which is a 
 function of the ``TOTHH`` input column.
@@ -449,9 +449,13 @@ which in turn uses skims from the skim_dict orca injectable.
 Finishing Up 
 ~~~~~~~~~~~~
 
-Back in the main ``simulation.py`` script, the next steps are to:
+The last models to be run by the data pipeline are:
+
+* ``write_data_dictionary``, which writes the table_name, number of rows, number of columns, and number of bytes for each checkpointed table
+* ``write_tables``, which writes pipeline tables as csv files as specified by the output_tables setting
+
+Back in the main ``simulation.py`` script, the final steps are to:
 
-* loop through the final data pipeline tables (households, persons, tours, trips, etc.) and write them to CSV files
 * close the data pipeline (and attached HDF5 file)
 * print the elapsed model runtime
 

docs/models.rst

@@ -511,6 +511,26 @@ API
 See :ref:`tour_mode_choice` API.
 
 
+
+
+.. _utility_steps:
+
+Utility Steps
+-------------
+Model step utilities for writing out pipeline data tables and for understanding 
+data table size.
+
+The main interfaces to the utility steps models are 
+:py:func:`~activitysim.abm.models.utility_steps.write_data_dictionary` and 
+:py:func:`~activitysim.abm.models.utility_steps.write_tables`.  These 
+functions are registered as orca steps in the example Pipeline.
+
+API
+~~~
+
+.. automodule:: activitysim.abm.models.utility_steps
+   :members:
+
 Util
 ----