Metadata-Version: 1.1
Name: fasttrips
Version: 1.0a2
Summary: Dynamic Transit Assignment Model. Given a transit network and a list of transit demand, finds a pathset and chooses a path for each traveler.
Home-page: http://fast-trips.mtc.ca.gov/
Author: MTC, SFCTA & PSRC
Author-email: lzorn@mtc.ca.gov
License: Apache
Description: fast-trips

        ==========

        

        fast-trips is a Dynamic Transit Assignment tool written in Python and

        supplemented by code in C++. For more information about this visit the

        following links: \* Project Website: http://fast-trips.mtc.ca.gov/ \*

        Full Technical Documentation (API): http://data.mtc.ca.gov/fast-trips/

        

        Contents

        --------

        

        -  `Setup <#setup>`__

        -  `Input <#input>`__

        -  ```config_ft.txt`` <#config_fttxt>`__

        

           -  `Configuration Options:

              fasttrips <#configuration-options-fasttrips>`__

           -  `Configuration Options:

              pathfinding <#configuration-options-pathfinding>`__

           -  `More on Overlap Path Size

              Penalites <#more-on-overlap-path-size-penalties>`__

        

        -  ```config_ft.py`` <#config_ftpy>`__

        -  ```pathweight_ft.txt`` <#pathweight_fttxt>`__

        -  `Fares <#fares>`__

        -  `Test Sample Input <#test-sample-input>`__

        -  `Test Network <#test-network>`__

        -  `Test Demand <#test-demand>`__

        -  `Test Runs <#test-runs>`__

        -  `Summarizing Results <#summarizing-results>`__

        -  `Frequently Asked Questions <#frequently-asked-questions>`__

        -  `References <#references>`__

        -  `Changelog <#changelog>`__

        

        Setup

        -----

        

        Follow the steps below to setup up fast-trips: \* Install

        `Git <https://git-scm.com/>`__ and clone the fast-trips repository

        (https://github.com/MetropolitanTransportationCommission/fast-trips.git)

        to a local directory: ``<fast-trips-dir>``. If the user plans on making

        changes to the code, it is recommended that the repository be

        `forked <https://help.github.com/articles/fork-a-repo/>`__ before

        cloning. \* Switch to the ``develop`` branch of the repository. \*

        Download and install `numpy <http://www.numpy.org/>`__ and

        `pandas <http://pandas.pydata.org/>`__. One option is to install a *data

        analytics* Python 2.7 distribution which bundles these, like

        `Anaconda <https://www.continuum.io/downloads>`__. Windows users can

        also find package installers

        `here <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`__. \* If compiling

        on Windows, install `Microsoft Visual C++ Compiler for Python

        2.7 <http://www.microsoft.com/en-us/download/details.aspx?id=44266>`__.

        On Linux, install the python-dev package. \* Install the python package

        `transitfeed <https://github.com/google/transitfeed/wiki/TransitFeed>`__

        for reading GTFS. \* Set the ``PYTHONPATH`` environment variable to the

        location of your fast-trips repo, which we're calling

        ``<fast-trips-dir>``. \* To build, in the fast-trips directory

        ``<fast-trips-dir>``, run the following in a command prompt:

        ``python setup.py build_ext --inplace``.

        

        Input

        -----

        

        The input to fast-trips consists of: \* A Transit Network directory,

        including schedules, access, egress and transfer information, specified

        by the `GTFS-Plus Data Standards

        Repository <https://github.com/osplanning-data-standards/GTFS-PLUS>`__

        \* A Transit Demand directory, including persons, households and trips,

        specified by the `Demand Data Standards

        Repository <https://github.com/osplanning-data-standards/dyno-demand>`__

        \* fast-trips Configuration, specified below

        

        Configuration is specified in the following files:

        

        ``config_ft.txt``

        ~~~~~~~~~~~~~~~~~

        

        This is a *required* python file and may be included in both the Transit

        Supply and Transit Demand input directories. If the same options are

        specified in both, then the version specified in the Transit Demand

        input directory will be used. (Two versions may be specified because

        some configuration options are more relevant to demand and some are more

        relevant to network inputs.)

        

        The configuration files are parsed by python's `ConfigParser

        module <https://docs.python.org/2/library/configparser.html#module-ConfigParser>`__

        and therefore adhere to that format, with two possible sections:

        *fasttrips* and *pathfinding*. (See `Network

        Example <Examples/test_network/input/config_ft.txt>`__ ) (See `Demand

        Example <Examples/test_network/demand_twopaths/config_ft.txt>`__ )

        

        Configuration Options: fasttrips

        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

        

        +-------------+-------+-----------+---------------------------+

        | Option Name | Type  | Default   | Description               |

        +=============+=======+===========+===========================+

        | ``bump_buff | float | 5         | Not really used yet.      |

        | er``        |       |           |                           |

        +-------------+-------+-----------+---------------------------+

        | ``bump_one_ | bool  | False     |

        | at_a_time`` |       |           |

        +-------------+-------+-----------+---------------------------+

        | ``capacity_ | bool  | False     | Hard capacity constraint. |

        | constraint` |       |           | When True, fasttrips      |

        | `           |       |           | forces everyone off       |

        |             |       |           | overcapacity vehicles and |

        |             |       |           | disallows them from       |

        |             |       |           | finding a new path using  |

        |             |       |           | an overcapacity vehicle.  |

        +-------------+-------+-----------+---------------------------+

        | ``create_sk | bool  | False     | Not implemented yet.      |

        | ims``       |       |           |                           |

        +-------------+-------+-----------+---------------------------+

        | ``debug_num | int   | -1        | If positive, will         |

        | _trips``    |       |           | truncate the trip list to |

        |             |       |           | this length.              |

        +-------------+-------+-----------+---------------------------+

        | ``debug_tra | bool  | False     | If True, will only find   |

        | ce_only``   |       |           | paths and simulate the    |

        |             |       |           | person ids specified in   |

        |             |       |           | ``trace_person_ids``.     |

        +-------------+-------+-----------+---------------------------+

        | ``debug_out | bool  | False     | If True, will write       |

        | put_columns |       |           | internal & debug columns  |

        | ``          |       |           | into output.              |

        +-------------+-------+-----------+---------------------------+

        | ``fare_zone | bool  | False     | If True, will assume fare |

        | _symmetry`` |       |           | zone symmetry. That is,   |

        |             |       |           | if fare\_id X is          |

        |             |       |           | configured from origin    |

        |             |       |           | zone A to destination     |

        |             |       |           | zone B, and there is no   |

        |             |       |           | fare configured from zone |

        |             |       |           | B to zone A, we'll assume |

        |             |       |           | that fare\_id X also      |

        |             |       |           | applies.                  |

        +-------------+-------+-----------+---------------------------+

        | ``max_itera | int   | 1         | Maximum number of         |

        | tions``     |       |           | pathfinding iterations to |

        |             |       |           | run.                      |

        +-------------+-------+-----------+---------------------------+

        | ``number_of | int   | 0         | Number of processes to    |

        | _processes` |       |           | use for path finding.     |

        | `           |       |           |                           |

        +-------------+-------+-----------+---------------------------+

        | ``output_pa | bool  | True      | Write chosen passenger    |

        | ssenger_tra |       |           | paths? TODO: deprecate.   |

        | jectories`` |       |           | Why would you ever not do |

        |             |       |           | this?                     |

        +-------------+-------+-----------+---------------------------+

        | ``output_pa | bool  | False     | Output pathsets for each  |

        | thset_per_s |       |           | simulation iteration? If  |

        | im_iter``   |       |           | false, just outputs once  |

        |             |       |           | per path-finding          |

        |             |       |           | iteration.                |

        +-------------+-------+-----------+---------------------------+

        | ``prepend_r | bool  | False     | This is for readability   |

        | oute_id_to_ |       |           | in debugging; if True,    |

        | trip_id``   |       |           | then route ids will be    |

        |             |       |           | prepended to trip ids.    |

        +-------------+-------+-----------+---------------------------+

        | ``simulatio | bool  | True      | Simulate transit          |

        | n``         |       |           | vehicles? After           |

        |             |       |           | path-finding, should      |

        |             |       |           | fast-trips update vehicle |

        |             |       |           | times and put passengers  |

        |             |       |           | on vehicles? If False,    |

        |             |       |           | fast-trips still          |

        |             |       |           | calculates costs and      |

        |             |       |           | probabilities and chooses |

        |             |       |           | paths, but the vehicle    |

        |             |       |           | times will not be updated |

        |             |       |           | from those read in from   |

        |             |       |           | the input network, and    |

        |             |       |           | passengers will not be    |

        |             |       |           | loaded onto vehicles.     |

        |             |       |           | This is useful for        |

        |             |       |           | debugging path-finding    |

        |             |       |           | and verifying that        |

        |             |       |           | pathfinding calculations  |

        |             |       |           | are consistent with       |

        |             |       |           | cost/fare calculations    |

        |             |       |           | done outside pathfinding. |

        +-------------+-------+-----------+---------------------------+

        | ``skim_star | strin | 5:00      | Not implemented yet.      |

        | t_time``    | g     |           |                           |

        +-------------+-------+-----------+---------------------------+

        | ``skim_end_ | strin | 10:00     | Not implemented yet.      |

        | time``      | g     |           |                           |

        +-------------+-------+-----------+---------------------------+

        | ``skip_pers | strin | 'None'    | A list of person IDs to   |

        | on_ids``    | g     |           | skip.                     |

        +-------------+-------+-----------+---------------------------+

        | ``trace_ids | strin | 'None'    | A list of tuples, (person |

        | ``          | g     |           | ID, person trip ID), for  |

        |             |       |           | whom to output verbose    |

        |             |       |           | trace information.        |

        +-------------+-------+-----------+---------------------------+

        

        Configuration Options: pathfinding

        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

        

        +-------------+-------+-----------+-------------+

        | Option Name | Type  | Default   | Description |

        +=============+=======+===========+=============+

        | ``max_num_p | int   | -1        | If          |

        | aths``      |       |           | positive,   |

        |             |       |           | drops paths |

        |             |       |           | after this  |

        |             |       |           | IF          |

        |             |       |           | probability |

        |             |       |           | is less     |

        |             |       |           | than        |

        |             |       |           | \`\ ````\ m |

        |             |       |           | in\_path\_p |

        |             |       |           | robability\ |

        |             |       |           |  ``| float  |

        |             |       |           |  | 0.005    |

        |             |       |           | | Paths wit |

        |             |       |           | h probabili |

        |             |       |           | ty less tha |

        |             |       |           | n this get  |

        |             |       |           | dropped IF` |

        |             |       |           | `\ max\_num |

        |             |       |           | \_paths\ `` |

        |             |       |           | specified A |

        |             |       |           | ND hit.``\  |

        |             |       |           | min\_transf |

        |             |       |           | er\_penalty |

        |             |       |           | \ ``| float |

        |             |       |           |   | 1       |

        |             |       |           |  | Minimum  |

        |             |       |           | transfer pe |

        |             |       |           | nalty. Safe |

        |             |       |           | guard again |

        |             |       |           | st having n |

        |             |       |           | o transfer  |

        |             |       |           | penalty whi |

        |             |       |           | ch can resu |

        |             |       |           | lt in terri |

        |             |       |           | ble paths w |

        |             |       |           | ith excessi |

        |             |       |           | ve transfer |

        |             |       |           | s.``\ overl |

        |             |       |           | ap\_chunk\_ |

        |             |       |           | size\ ``| i |

        |             |       |           | nt    | 500 |

        |             |       |           |      | How  |

        |             |       |           | many person |

        |             |       |           | 's trips to |

        |             |       |           |  process at |

        |             |       |           |  a time in  |

        |             |       |           | overlap cal |

        |             |       |           | culations i |

        |             |       |           | n python si |

        |             |       |           | mulation (m |

        |             |       |           | ore means f |

        |             |       |           | aster but m |

        |             |       |           | ore memory  |

        |             |       |           | required.)` |

        |             |       |           | `\ overlap\ |

        |             |       |           | _scale\_par |

        |             |       |           | ameter\ ``| |

        |             |       |           |  float  | 1 |

        |             |       |           |        | Sc |

        |             |       |           | ale paramet |

        |             |       |           | er for over |

        |             |       |           | lap path si |

        |             |       |           | ze variable |

        |             |       |           | .``\ overla |

        |             |       |           | p\_split\_t |

        |             |       |           | ransit\ ``| |

        |             |       |           |  bool   | F |

        |             |       |           | alse   | Fo |

        |             |       |           | r overlap c |

        |             |       |           | alcs, split |

        |             |       |           |  transit le |

        |             |       |           | g into comp |

        |             |       |           | onent legs  |

        |             |       |           | (A to E bec |

        |             |       |           | auses A-B-C |

        |             |       |           | -D-E)``\ ov |

        |             |       |           | erlap\_vari |

        |             |       |           | able\ ``| s |

        |             |       |           | tring | 'co |

        |             |       |           | unt' | The  |

        |             |       |           | variable up |

        |             |       |           | on which to |

        |             |       |           |  base the o |

        |             |       |           | verlap path |

        |             |       |           |  size varia |

        |             |       |           | ble.  Can b |

        |             |       |           | e one of``\ |

        |             |       |           |  None\ ``,` |

        |             |       |           | `\ count\ ` |

        |             |       |           | `,``\ dista |

        |             |       |           | nce\ ``,``\ |

        |             |       |           |  time\ ``.` |

        |             |       |           | `\ pathfind |

        |             |       |           | ing\_type\  |

        |             |       |           | ``| string  |

        |             |       |           | | 'stochast |

        |             |       |           | ic' | Pathf |

        |             |       |           | inding meth |

        |             |       |           | od.  Can be |

        |             |       |           | ``\ stochas |

        |             |       |           | tic\ ``,``\ |

        |             |       |           |  determinis |

        |             |       |           | tic\ ``, or |

        |             |       |           | ``\ file\ ` |

        |             |       |           | `.``\ pathw |

        |             |       |           | eights\_fix |

        |             |       |           | ed\_width\  |

        |             |       |           | ``| bool    |

        |             |       |           | | False   | |

        |             |       |           |  If true, r |

        |             |       |           | ead the pat |

        |             |       |           | hweights fi |

        |             |       |           | le as a fix |

        |             |       |           | ed width, l |

        |             |       |           | eft-justifi |

        |             |       |           | ed table (a |

        |             |       |           | s opposed t |

        |             |       |           | o a CSV, wh |

        |             |       |           | ich is the  |

        |             |       |           | default).`` |

        |             |       |           | \ stochasti |

        |             |       |           | c\_dispersi |

        |             |       |           | on\ ``| flo |

        |             |       |           | at  | 1.0   |

        |             |       |           |    | Stocha |

        |             |       |           | stic disper |

        |             |       |           | sion parame |

        |             |       |           | ter. TODO:  |

        |             |       |           | document th |

        |             |       |           | is further. |

        |             |       |           | ``\ stochas |

        |             |       |           | tic\_max\_s |

        |             |       |           | top\_proces |

        |             |       |           | s\_count\ ` |

        |             |       |           | `| int    | |

        |             |       |           |  -1      |  |

        |             |       |           | In path-fin |

        |             |       |           | ding, how m |

        |             |       |           | any times s |

        |             |       |           | hould we pr |

        |             |       |           | ocess a sto |

        |             |       |           | p during la |

        |             |       |           | beling?  Sp |

        |             |       |           | ecify -1 fo |

        |             |       |           | r no max.`` |

        |             |       |           | \ stochasti |

        |             |       |           | c\_pathset\ |

        |             |       |           | _size\ ``|  |

        |             |       |           | int    | 10 |

        |             |       |           | 00    | In  |

        |             |       |           | path-findin |

        |             |       |           | g, how many |

        |             |       |           |  paths (not |

        |             |       |           |  necessaril |

        |             |       |           | y unique) d |

        |             |       |           | etermine a  |

        |             |       |           | pathset?``\ |

        |             |       |           |  time\_wind |

        |             |       |           | ow\ ``| flo |

        |             |       |           | at  | 30    |

        |             |       |           |    | In pat |

        |             |       |           | h-finding,  |

        |             |       |           | the max tim |

        |             |       |           | e a passeng |

        |             |       |           | er would wa |

        |             |       |           | it at a sto |

        |             |       |           | p.``\ trans |

        |             |       |           | fer\_fare\_ |

        |             |       |           | ignore\_pat |

        |             |       |           | hfinding\ ` |

        |             |       |           | `| bool   | |

        |             |       |           |  False   |  |

        |             |       |           | In path-fin |

        |             |       |           | ding, suppr |

        |             |       |           | ess trying  |

        |             |       |           | to adjust f |

        |             |       |           | ares using  |

        |             |       |           | transfer ru |

        |             |       |           | les.  For p |

        |             |       |           | erformance. |

        |             |       |           | ``\ transfe |

        |             |       |           | r\_fare\_ig |

        |             |       |           | nore\_pathe |

        |             |       |           | num\ ``| bo |

        |             |       |           | ol   | Fals |

        |             |       |           | e   | In pa |

        |             |       |           | th-enumerat |

        |             |       |           | ion, suppre |

        |             |       |           | ss trying t |

        |             |       |           | o adjust fa |

        |             |       |           | res using t |

        |             |       |           | ransfer rul |

        |             |       |           | es.  For pe |

        |             |       |           | rformance.` |

        |             |       |           | `\ user\_cl |

        |             |       |           | ass\_functi |

        |             |       |           | on\`        |

        +-------------+-------+-----------+-------------+

        

        More on Overlap Path Size Penalties

        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

        

        The path size overlap penalty is formulated by Ramming and discussed in

        Hoogendoorn-Lanser et al. (see `References <#references>`__ ).

        

        When the pathsize overlap is penalized (pathfinding ``overlap_variable``

        is not ``None``), then the following equation is used to calculate the

        path size overlap penalty:

        

        .. figure:: /doc/overlap_function.png

           :alt: Path Overlap Penalty Equation

        

           Path Overlap Penalty Equation

        

        Where \* *i* is the path alternative for individual *n* \* Γ\ *i*\  is

        the set of legs of path alternative *i* \* *la* is the value of the

        ``overlap_variable`` for leg *a*. So it is either 1, the distance or the

        time of leg *a* depending of if ``overlap_scale_parameter`` is

        ``count``, ``distance`` or ``time``, respectively. \* *Li is the total

        sum of the ``overlap_variable`` over all legs *\ la\* that make up path

        alternative *i* \* *Cin is the choice set of path alternatives for

        individual *\ n\* that overlap with alternative *i* \* γ is the

        ``overlap_scale_parameter`` \* δ\ *ai*\  = 1 and δ\ *aj*\  = 0 ∀ *j* ≠

        *i*

        

        From Hoogendoor-Lanser et al.:

        

            Consequently, if leg *a* for alternative *i* is unique, then [the

            denominator is equal to 1] and the path size contribution of leg *a*

            is equal to its proportional length *la/Li*. If leg *la* is also

            used by alternative *j*, then the contribution of leg *la* to path

            size PS\ *i*\  is smaller than *la/Li*. If γ = 0 or if routes *i*

            and *j* have equal length, then the contribution of leg *a* to

            PS\ *i*\  is equal to *la/2Li*. If γ > 0 and routes *i* and *j*

            differ in length, then the contribution of leg *a* to PS\ *i*\ 

            depends on the ratio of *Li* to *Lj*. If route *i* is longer than

            route *j* and γ > 1, then the contribution of leg *a* to PS\ *i*\ 

            is larger than *la/2Li*; otherwise, the contribution is smaller than

            *la/2Li*. If γ > 1 in the exponential path size formulation, then

            long routes are penalized in favor of short routes. The use of

            parameter γ is questionable if overlapping routes have more or less

            equal length and should therefore be set to 0. Overlap between those

            alternatives should not affect their choice probabilities

            differently. The degree to which long routes should be penalized

            might be determined by estimating γ. If γ is not estimated, then an

            educated guess with respect to γ should be made. To this end,

            differences in route length between alternatives in a choice set

            should be considered.

        

        ``config_ft.py``

        ~~~~~~~~~~~~~~~~

        

        This is an *optional* python file in the Transit Demand input directory

        containing functions that are evaluated. This could be used to

        programmatically define user classes based on person, household and/or

        trip attributes. To use a function in this file, specify it in the

        *pathfinding* configuration as the ``user_class_function``. (See

        `Example <Examples/test_network/demand_twopaths/config_ft.py>`__ )

        

        ``pathweight_ft.txt``

        ~~~~~~~~~~~~~~~~~~~~~

        

        The pathweight file is a *required* file that tells Fast-Trips how much

        to value each attribute of a path.

        

        The file can be a csv or fixed-format. If you use a fixed-format, make

        sure ``pathweights_fixed_width = True`` in the run configuration file

        (e.g., ``config_ft.txt``).

        

        ``pathweight_ft.txt`` **must** have the following columns:

        

        +-------------+-------+-------------+

        | Column Name | Type  | Description |

        +=============+=======+=============+

        | ``user_clas | Str   | Config      |

        | s``         |       | functions   |

        |             |       | can use     |

        |             |       | trip list,  |

        |             |       | person, and |

        |             |       | household   |

        |             |       | attributes  |

        |             |       | to return a |

        |             |       | user class  |

        |             |       | string to   |

        |             |       | the trip.   |

        |             |       | The string  |

        |             |       | that is     |

        |             |       | returned    |

        |             |       | determines  |

        |             |       | the set of  |

        |             |       | path        |

        |             |       | weights     |

        |             |       | that are    |

        |             |       | used. ( ??? |

        |             |       | is default  |

        |             |       | if no user  |

        |             |       | class       |

        |             |       | function ?  |

        |             |       | )           |

        +-------------+-------+-------------+

        | ``purpose`` | St    | This should |

        |             |       | match the   |

        |             |       | trip        |

        |             |       | purpose as  |

        |             |       | specified   |

        |             |       | in          |

        |             |       | ``trip_list |

        |             |       | .txt``      |

        +-------------+-------+-------------+

        | ``demand_mo | Str   | One of -    |

        | de_type``   |       | ``transfer` |

        |             |       | `,          |

        |             |       | -           |

        |             |       | ``access``, |

        |             |       | -           |

        |             |       | ``egress``, |

        |             |       | or          |

        |             |       | -``transit` |

        |             |       | `           |

        +-------------+-------+-------------+

        | ``demand_mo | Str   | One of: -   |

        | de``        |       | ``transfer` |

        |             |       | `,          |

        |             |       | - a string  |

        |             |       | specified   |

        |             |       | as          |

        |             |       | **access/eg |

        |             |       | ress        |

        |             |       | mode** in   |

        |             |       | ``trip_list |

        |             |       | .txt``      |

        |             |       | demand file |

        |             |       | (i.e.       |

        |             |       | ``walk``,   |

        |             |       | ``PNR``) ,  |

        |             |       | or - a      |

        |             |       | string      |

        |             |       | specified   |

        |             |       | as a        |

        |             |       | **transit   |

        |             |       | mode** in   |

        |             |       | ``trip_list |

        |             |       | .txt``      |

        |             |       | demand file |

        |             |       | (i.e.       |

        |             |       | ``local_bus |

        |             |       | ``,         |

        |             |       | ``commuter_ |

        |             |       | rail``)     |

        +-------------+-------+-------------+

        | ``supply_mo | Str   | For         |

        | de``        |       | ``demand_mo |

        |             |       | de_type=tra |

        |             |       | nsit``,     |

        |             |       | corresponds |

        |             |       | to the      |

        |             |       | transit     |

        |             |       | mode as     |

        |             |       | defined in  |

        |             |       | the         |

        |             |       | ```GTFS-Plu |

        |             |       | s`` <https: |

        |             |       | //github.co |

        |             |       | m/osplannin |

        |             |       | g-data-stan |

        |             |       | dards/GTFS- |

        |             |       | PLUS/blob/m |

        |             |       | aster/varia |

        |             |       | bles.md#mod |

        |             |       | e>`__       |

        |             |       | input       |

        |             |       | network.    |

        |             |       | For         |

        |             |       | ``demand_mo |

        |             |       | de_type=tra |

        |             |       | nsfer``     |

        |             |       | and         |

        |             |       | ``demand_mo |

        |             |       | de=transfer |

        |             |       | ``,         |

        |             |       | is one of   |

        |             |       | ``walk``,   |

        |             |       | ``wait``,   |

        |             |       | or          |

        |             |       | ``transfer_ |

        |             |       | penalty``.  |

        |             |       | For         |

        |             |       | ``demand_mo |

        |             |       | de_type = a |

        |             |       | ccess``,    |

        |             |       | is one of   |

        |             |       | ``walk_acce |

        |             |       | ss``,       |

        |             |       | ``bike_acce |

        |             |       | ss``,       |

        |             |       | ``pnr_acces |

        |             |       | s``,        |

        |             |       | or          |

        |             |       | ``knr_acces |

        |             |       | s``.        |

        |             |       | For         |

        |             |       | ``demand_mo |

        |             |       | de_type = e |

        |             |       | gress``,    |

        |             |       | is one of   |

        |             |       | ``walk_egre |

        |             |       | ss``,       |

        |             |       | ``bike_egre |

        |             |       | ss``,       |

        |             |       | ``pnr_egres |

        |             |       | s``,        |

        |             |       | or          |

        |             |       | ``knr_egres |

        |             |       | s``.        |

        +-------------+-------+-------------+

        | ``weight_na | Str   | An          |

        | me``        |       | attribute   |

        |             |       | of the path |

        |             |       | link. See   |

        |             |       | below for   |

        |             |       | more        |

        |             |       | details.    |

        +-------------+-------+-------------+

        | ``weight_va | Float | The         |

        | lue``       |       | multiplier  |

        |             |       | for the     |

        |             |       | attribute   |

        |             |       | named       |

        |             |       | ``weight_na |

        |             |       | me``        |

        +-------------+-------+-------------+

        

        *Notes*:

        

        1. If demand mode X has supply mode Y, that means a trip specified as

           transit mode X in the ``trip_list.txt`` may use a transit link

           specified as Y in the network. Moreover, if the trip list were to

           specify that someone takes ``commuter_rail`` (like if the ABM chooses

           the primary mode for them as commuter rail), then they can still take

           a local bus or any lesser mode on their trip in addition to commuter

           rail. Often in this case, the weights are assumed to be higher for

           non-commuter rail modes and lower for commuter rail to induce them to

           ride. For example:

        

        +---------------------+-------------------+---------------------------+--------------------+

        | ``demand_mode``     | ``supply_mode``   | ``weight_name``           | ``weight_value``   |

        +=====================+===================+===========================+====================+

        | ``commuter_rail``   | ``local_bus``     | ``in_vehicle_time_min``   | 1.5                |

        +---------------------+-------------------+---------------------------+--------------------+

        | ``commuter_rail``   | ``heavy_rail``    | ``in_vehicle_time_min``   | 1.0                |

        +---------------------+-------------------+---------------------------+--------------------+

        

        ``Weight_Name`` Values

        ~~~~~~~~~~~~~~~~~~~~~~

        

        The following is an example of a minimally specified

        ``pathweight_ft.txt`` :

        

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``demand_mode_type``   | ``demand_mode``   | ``supply_mode``   | ``weight_name``           | ``weight_value``   |

        +========================+===================+===================+===========================+====================+

        | ``access``             | ``walk``          | ``walk_access``   | ``time_min``              | 2                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``egress``             | ``walk``          | ``walk_egress``   | ``time_min``              | 2                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``transit``            | ``transit``       | ``local_bus``     | ``wait_time_min``         | 2                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``transit``            | ``transit``       | ``local_bus``     | ``in_vehicle_time_min``   | 1                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``transfer``           | ``transfer``      | ``transfer``      | ``transfer_penalty``      | 5                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        | ``transfer``           | ``transfer``      | ``transfer``      | ``time_min``              | 2                  |

        +------------------------+-------------------+-------------------+---------------------------+--------------------+

        

        For most of the weights prefix mode is not needed. E.g. there is no need

        to label ``weight_name`` ``time_min`` for ``supply_mode``

        ``walk_access`` as ``walk_time_min``, because the fact that the

        ``supply_mode`` is ``walk_access`` means it is only assessed on walk

        links. The drive option (PNR/KNR access/egress), however, should have

        ``walk_`` and ``drive_`` prefixes, because the access can have both

        components: driving to the station from the origin and walking from the

        lot to the station. So for example, for ``supply_mode`` ``pnr_access``

        there will be two weights associated with travel time: ``walk_time_min``

        and ``drive_time_min``.

        

        The following is a partial list of possible weight names base don the

        demand mode / supply mode combinations.

        

        ``demand_mode_type = access`` / ``demand_mode = walk`` /

        ``supply_mode = walk_access``

        

        -  ``time_min``

        -  ``elevation_gain``

        -  ``preferred_delay_min``

        

        ``demand_mode_type = egress`` / ``demand_mode = walk`` /

        ``supply_mode = walk_egress``

        

        -  ``time_min``

        -  ``elevation_gain``

        -  ``preferred_delay_min``

        

        ``demand_mode_type = access`` / ``demand_mode = PNR`` /

        ``supply_mode = pnr_access``

        

        -  ``walk_time_min``

        -  ``drive_time_min``

        

        ``demand_mode_type = transfer`` / ``demand_mode = transfer`` /

        ``supply_mode = transfer``

        

        -  ``transfer_penalty``

        -  ``time_min``

        -  ``wait_time_min``

        

        ``demand_mode_type = transit`` / ``demand_mode = transit`` /

        ``supply_mode = <pick a transit mode>``

        

        -  ``in_vehicle_time_min``

        -  ``wait_time_min``

        

        Note that the cost component is handled at the path level using the

        value of time column in ``trip_list.txt``.

        

        Fares

        -----

        

        GTFS-plus fare inputs are similar to GTFS fare inputs but with

        additional fare periods for time period-based fares.

        

        However, since the columns ``route_id``, ``origin_id``,

        ``destination_id`` and ``contains_id`` are all optional in

        `fare\_rules.txt <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_rules.md>`__

        and therefore may be specified in different combinations, fast-trips

        implements fares with the following rules:

        

        -  ``contains_id`` is not implemented in fast-trips, and its inclusion

           will result in an error

        -  Specifying ``origin_id`` and not ``destination_id`` or vice versa

           will result in an error. Each fare rule must specify both or neither.

        -  These combinations of ``route_id``, ``origin_id``, and

           ``destination_id`` will be used to match a ``fare_id`` to a transit

           trip, in this order. The first match will win.

        -  Matching ``route_id``, ``origin_id`` and ``destination_id``

        -  Matching ``route_id`` only (no ``origin_id`` or ``destination_id``

           specified)

        -  Matching ``origin_id`` and ``destination_id`` only (no ``route_id``

           specified)

        -  No match (e.g. ``fare_id`` specified with no other columns)

        

        Discount and free transfers specified in

        `fare\_transfer\_rules\_ft.txt <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_transfer_rules_ft.md>`__

        are applied to transfers from one fare period to another fare period,

        and these links need to be *back-to-back*. So if a passenger transfers

        from A to B to C and the discount is specified for fare period A to fare

        period C, they will not receive the discount.

        

        Free transfers are also specified *within* fare periods (possibly

        time-bounded) in

        `fare\_attributes\_ft.txt <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_attributes_ft.md>`__.

        These free transfers are applied *after* the discounts from

        `fare\_transfer\_rules\_ft.txt <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_transfer_rules_ft.md>`__

        and they do not need to be back-to-back. So if a passenger transfers

        from A to B to A and fare period A has 1 free transfer specified, but a

        transfer from B to A has a transfer fare of $.50, the passenger will

        receive the free transfer since these rules are applied last (and

        override).

        

        There are four places where fares factor into fast-trips.

        

        1. During path-finding (C++ extension), fares get assessed as a cost

           onto links, which translate to generalized cost (minutes) via the

           traveler's value of time. `Fare transfer

           rules <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_transfer_rules_ft.md>`__

           here are complicated, because we don't know which is the

           next/previous fare, and we can only guess based on probabilities. The

           fare is estimated using

           ```Hyperlink::getFareWithTransfer()`` <src/hyperlink.cpp>`__.

        

        Free transfers as configured in `fare

        attributes <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_attributes_ft.md>`__

        are implemented here in a simplistic way; that is, a free transfer is

        assumed if the fare attributes have granted any free transfers without

        looking at ``transfer_duration`` or the number of transfers. Also, this

        transfer is required to be *back-to-back* also. A future enhancement

        could include keeping a transfer count for each fare period so that the

        back-to-back requirement is not imposed, and also so that a certain

        number of free fares could be tallied, but at this time, a simpler

        approach is used because it's not clear if this kind of detail is

        helpful.

        

        Turn this off using configuration option

        ``transfer_fare_ignore_pathfinding``.

        

        2. During path-enumeration (C++ extension), when the paths are being

           constructed by choosing links from the hyperpath graph, at the point

           where each link is added to the path, the `fare transfer

           rules <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_transfer_rules_ft.md>`__

           are applied to adjust fares with more certainty of the the path so

           far. This is done in

           ```Hyperlink::setupProbabilities()`` <src/hyperlink.cpp>`__ which

           calls ``Hyperlink::updateFare()`` and updates the link cost as well

           if the fare is affected. Free transfers as configured in `fare

           attributes <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_attributes_ft.md>`__

           are looked at here as well, but without the transfer duration

           component.

        

        3. During path-enumeration (C++ extension), after the path is

           constructed, the trip cost is re-calculated at the end using

           ```Path::calculateCost()`` <src/path.cpp>`__. At this moment in the

           process, the path is complete and final, so the fare transfer rules

           are relatively easy to apply given that links are certain. The

           initial fare and cost are saved and passed back to python to show the

           effect of step 1.

        

        Free transfers as configured in `fare

        attributes <https://github.com/osplanning-data-standards/GTFS-PLUS/blob/master/files/fare_attributes_ft.md>`__

        are also addressed here.

        

        Turn this off using configuration option

        ``transfer_fare_ignore_pathenum``.

        

        4. During simulation (python), while the path is being adjusted due to

           vehicle times, the fares are calculated via

           ```Route.add_fares()`` <fasttrips/Route.py>`__. This is unlikely to

           change anything unless the fare periods changed due to the slow-down

           of vehicles -- so consider deprecating this in favor of using the

           pathfinding results? For now, it's a good test that the C++ code is

           working as expected; running with simulation off should result in

           identical fare and cost results from pathfinding and the

           (non-vehicle-updating) python simulation.

        

        Test Sample Input

        -----------------

        

        Sample input files have been provided in

        ``<fast-trips-dir>\Examples\test_network`` to test the setup and also

        assist with the creation of new fast-trips runs. The input files include

        network files created from a small hypothetical test network and also

        example transit demand data. To quickly test the setup, run fast-trips

        on sample input using the following steps: \* Add ``<fast-trips-dir>``

        to the ``PYTHONPATH`` environment variable in *Advanced system

        settings*. \* Run ``\scripts\runAllTests.bat`` from within

        ``<fast-trips-dir>`` in a command prompt. This will run several "preset"

        parameter combinations. The user can alternatively run each parameter

        combination individually using the commands listed in the batch file.

        Details about the test runs are provided in subsequent sections. Output

        files from running fast-trips with the sample input data provided can be

        found in the ``output`` directory.

        

        Test Network

        ~~~~~~~~~~~~

        

        A hypothetical 5-zone test network was developed to help code

        development. It has a total of three transit routes (one rail and two

        bus) with two or three stops each. There are also two park-and-ride

        (PnR) locations.

        

        .. figure:: /Examples/test_network/input/test_network.png

           :alt: Transit Test Network

        

           alt text

        

        Transit vehicles commence at 3:00 PM and continue until 6:00 PM. There

        are 152 transit trips that make a total of 384 station stops. ``input``

        folder contains all the supply-side/network input files prepared from

        the test network. More information about network input file standards

        can be found in the `GTFS-Plus Data Standards

        Repository <https://github.com/osplanning-data-standards/GTFS-PLUS>`__.

        

        Test Demand

        ~~~~~~~~~~~

        

        Two versions of sample demand have been prepared: \* ``demand_reg``

        contains regular demand that consists only of a transit trip list. There

        are no multiple user classes and all trips use a single set of path

        weights (``pathweight_ft.txt``). Demand starts at 3:15 PM and ends at

        5:15 PM.One trip occurs every 10 seconds. More information is available

        in `documentation </Examples/test_network/demand_reg/Readme.md>`__. \*

        ``demand_twopaths`` represents demand for two user classes that use

        different sets of path weights. Household and person attribute files are

        present in addition to the trip list to model user heterogeneity and

        multiple user classes.

        

        Similar to network data standards, there also exists a `Demand Data

        Standards

        Repository <https://github.com/osplanning-data-standards/dyno-demand>`__.

        

        Test Runs

        ---------

        

        There are a total of six test runs in ``\scripts\runAllTests.bat``. Type

        of assignment, capacity constraint, and number of iterations are varied

        in addition to the demand.

        

        +-------+---------------+-------------------+--------------+-----------------------+

        | Sno   | Demand        | Assignment Type   | Iterations   | Capacity Constraint   |

        +=======+===============+===================+==============+=======================+

        | 1     | Multi-class   | Deterministic     | 2            | On                    |

        +-------+---------------+-------------------+--------------+-----------------------+

        | 2     | Multi-class   | Stochastic        | 1            | Off                   |

        +-------+---------------+-------------------+--------------+-----------------------+

        | 3     | Multi-class   | Stochastic        | 2            | On                    |

        +-------+---------------+-------------------+--------------+-----------------------+

        | 4     | Regular       | Deterministic     | 2            | On                    |

        +-------+---------------+-------------------+--------------+-----------------------+

        | 5     | Regular       | Stochastic        | 1            | Off                   |

        +-------+---------------+-------------------+--------------+-----------------------+

        | 6     | Regular       | Stochastic        | 2            | On                    |

        +-------+---------------+-------------------+--------------+-----------------------+

        

        Type of Assignment: \* "Deterministic" indicates use of a deterministic

        trip-based shortest path search algorithm \* "Stochastic" indicates use

        of a stochastic hyperpath-finding algorithm

        

        Summarizing Results

        -------------------

        

        Fast-Trips will output results in the

        `dyno-path <https://github.com/osplanning-data-standards/dyno-path>`__

        format, which can be used to generate summary dashboards in Tableau or

        other reports.

        

        Creating Tableau Dashboard

        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        

        Frequently Asked Questions

        --------------------------

        

        -  How do I restart a run after pathfinding?

        

        Use the option ``pathfinding_type=file``, via

        ```runTest.py`` <scripts/runTest.py>`__ or in the configuration. Then,

        drop the ``pathsfound_paths.csv`` and ``pathsfound_links.csv`` files in

        the output directory for your run, and they'll be read in instead of

        generated.

        

        References

        ----------

        

        -  Ramming, M. S. *Network Knowledge and Route Choice.* Ph.D. Thesis.

           Massachusetts Institute of Technology, Cambridge, Mass., 2002.

        

        -  Hoogendoorn-Lanser, S., R. Nes, and P. Bovy. Path Size Modeling in

           Multinomial Route Choice Analysis. 27 In *Transportation Research

           Record: Journal of the transportation Research Board, No 1921*, 28

           Transportation Research Board of the National Academies, Washington,

           D.C., 2005, pp. 27-34.

        

        Changelog

        ---------

        

        Major changes to fast-trips since the original FAST-TrIPs

        (https://github.com/MetropolitanTransportationCommission/FAST-TrIPs-1)

        

        To be filled in further but including: \* Added pathfinding iterations

        to looping (so pathfinding\_iteration=1 finds paths for everyone, and

        subsequently just find paths for people who don't have a valid path.

        Break when max or we don't find anymore) \* Added time-period based

        drive access links (10/2016) \* Added link distance to extension as part

        of StopState (10/2016) \* Implemented overlap pathsize correction

        (8/2016) \* Add purpose segmentation to cost weighting (7/2016) \*

        Output pathsets in addition to chosen paths (4/2016) \* Update transit

        trip vehicle times based on boards, alights and vehicle-configured

        accleration, deceleration and dwell formulas (4/2016) \* Output

        performance measures (pathfinding and path enumeration times, number of

        stops processed) (3/2016) \* Stop order update to pathfinding: when a

        stop state is updated, mark other reachable stops for reprocessing

        (3/2016)

        `details <https://github.com/MetropolitanTransportationCommission/fast-trips/pull/22>`__

        \* Support KNR and PNR access (11/2015) \* Read user-class based cost

        weighting (11/2015) \* Switch input format to GTFS-plus network

        (10/2015) \* Move path finding to C++ extension (9/2015) \* Parallelized

        path finding with multiprocessing (7/2015) \* Port original FAST-TrIPs

        codebase to python with debug tracing (5/2015)

        
Keywords: transit model dynamic passenger assignment simulation
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Other Audience
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
