[Travelr-commits] r13 - pre-alpha pre-alpha/travelr pre-alpha/travelr/R pre-alpha/travelr/man pre-alpha/travelr/tests www
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed May 5 03:50:43 CEST 2010
Author: jrawbits
Date: 2010-05-05 03:50:40 +0200 (Wed, 05 May 2010)
New Revision: 13
Added:
pre-alpha/travelr/R/Cost_Integrator.R
pre-alpha/travelr/man/objective.functions.Rd
pre-alpha/travelr/man/parse.control.Rd
pre-alpha/travelr_0.1-4.zip
Removed:
pre-alpha/travelr_0.1-3.zip
Modified:
pre-alpha/travelr/DESCRIPTION
pre-alpha/travelr/R/Assignment_Set.R
pre-alpha/travelr/R/Highway_Assignment.R
pre-alpha/travelr/R/Path_Functions.R
pre-alpha/travelr/man/assignment.class.Rd
pre-alpha/travelr/man/assignment.functions.Rd
pre-alpha/travelr/man/assignment.set.Rd
pre-alpha/travelr/man/bpr.function.Rd
pre-alpha/travelr/man/build.intercepts.Rd
pre-alpha/travelr/man/build.network.set.Rd
pre-alpha/travelr/man/build.paths.Rd
pre-alpha/travelr/man/cost.functions.Rd
pre-alpha/travelr/man/free.flow.Rd
pre-alpha/travelr/man/highway.assign.Rd
pre-alpha/travelr/man/highway.net.Rd
pre-alpha/travelr/man/intercept.set.Rd
pre-alpha/travelr/man/ipf.Rd
pre-alpha/travelr/man/node.map.Rd
pre-alpha/travelr/man/package.Rd
pre-alpha/travelr/man/reaggregate.Rd
pre-alpha/travelr/man/sample.networks.Rd
pre-alpha/travelr/man/shortest.paths.Rd
pre-alpha/travelr/man/skim.paths.Rd
pre-alpha/travelr/man/tntp.Rd
pre-alpha/travelr/man/utilities.Rd
pre-alpha/travelr/tests/Test_05_SiouxFallsExample.R
www/
Log:
Extensively reworked and added to documentation.
Added copyright and license code to documentation files.
Separated cost.integrator function into its own slightly-separated file with Creative Commons Share-Alike license and GNU FDL, per the original code source at Wikipedia. The licensing is annoying, but it's important to stay as honest and legal as possible.
Modified: pre-alpha/travelr/DESCRIPTION
===================================================================
--- pre-alpha/travelr/DESCRIPTION 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/DESCRIPTION 2010-05-05 01:50:40 UTC (rev 13)
@@ -1,5 +1,5 @@
Package: travelr
-Version: 0.1-3
+Version: 0.1-4
Date: 2009-04-26
Title: Functions for Travel Demand Modeling
Author: Jeremy Raw
Modified: pre-alpha/travelr/R/Assignment_Set.R
===================================================================
--- pre-alpha/travelr/R/Assignment_Set.R 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/R/Assignment_Set.R 2010-05-05 01:50:40 UTC (rev 13)
@@ -14,6 +14,15 @@
# A copy of the GNU General Public License is available at
# http://www.r-project.org/Licenses/
# and included in the R distribution (in directory ‘share/licenses’).
+#
+# In addition, the code for the two functions "cost.integrator" and "inner.integrator"
+# was adapted from Wikipedia. These specific functions are copyrighted as noted above
+# and distributed under the Creative Commons Share-Alike License 3.0, which is available at
+# http://creativecommons.org/licenses/by-sa/3.0/
+# The "cost.integrator" and "inner.integrator" code is additionally available (as the
+# base code had not been modified at Wikipedia since before June, 2009) under the terms
+# of the GNU Free Documentation License, available here:
+# http://en.wikipedia.org/wiki/Wikipedia:GFDL
####################################################################################################
# This file defines the Assignment Set mechanism for handling single and multi-class assignment
@@ -322,93 +331,6 @@
}
# From Wikipedia:
-#
-# Here is an implementation of the adaptive Simpson's method in C99 that avoids
-# redundant evaluations of f and quadrature computations, but also suffers from
-# memory runaway. Suggested improvement would be to use a for loop in
-# adaptiveSimpsonsAux:
-#
-# #include <math.h> // include file for fabs and sin
-# #include <stdio.h> // include file for printf
-#
-# //
-# // Recursive auxiliary function for adaptiveSimpsons() function below
-# //
-# double adaptiveSimpsonsAux(double (*f)(double), double a, double b, double epsilon,
-# double S, double fa, double fb, double fc, int bottom) {
-# double c = (a + b)/2, h = b - a;
-# double d = (a + c)/2, e = (c + b)/2;
-# double fd = f(d), fe = f(e);
-# double Sleft = (h/12)*(fa + 4*fd + fc);
-# double Sright = (h/12)*(fc + 4*fe + fb);
-# double S2 = Sleft + Sright;
-# if (bottom <= 0 || fabs(S2 - S) <= 15*epsilon)
-# return S2 + (S2 - S)/15;
-# return adaptiveSimpsonsAux(f, a, c, epsilon/2, Sleft, fa, fc, fd, bottom-1) +
-# adaptiveSimpsonsAux(f, c, b, epsilon/2, Sright, fc, fb, fe, bottom-1);
-# }
-#
-# //
-# // Adaptive Simpson's Rule
-# //
-# double adaptiveSimpsons(double (*f)(double), // ptr to function
-# double a, double b, // interval [a,b]
-# double epsilon, // error tolerance
-# int maxRecursionDepth) { // recursion cap
-# double c = (a + b)/2, h = b - a;
-# double fa = f(a), fb = f(b), fc = f(c);
-# double S = (h/6)*(fa + 4*fc + fb);
-# return adaptiveSimpsonsAux(f, a, b, epsilon, S, fa, fb, fc, maxRecursionDepth);
-# }
-#
-#
-# int main(){
-# double I = adaptiveSimpsons(sin, 0, 1, 0.000000001, 10); // compute integral of sin(x)
-# // from 0 to 1 and store it in
-# // the new variable I
-# printf("I = %lf\n",I); // print the result
-# return 0;
-# }
-#
-# The "runaway memory" problem could potentially be an issue in the R code, but the
-# Wikipedia-suggested solution of unrolling the recursion into a loop is overkill if the cost
-# function is well-behaved. Time and experience will tell if we need to revisit this
-
-# Note: cost integrator can handle the special requirement that the volume and cost parameters be
-# vectors (and that the integral of the whole be the sum of the integrals of each element from "free
-# flow" volume (0) to the corresponding element in "congested"). This function should also handle
-# everything happily even if ff.vol and cong.vol are data.frames or matrices.
-
-# The standard R 'integrate' function can't do any of that...
-
-cost.integrator <- function( cost.function, ff.vol, ff.cost, cong.vol, cong.cost, tol=1e-8, max.depth=14 ) {
- # Integrate the cost function using adaptive quadrature with inside-interval tolerance testing
- ivl <- (cong.vol-ff.vol)/2
- mid.vol <- ff.vol+ivl
- mid.cost <- cost.function(mid.vol)
- result <- (ivl/3)*(ff.cost+4*mid.cost+cong.cost)
- inner.integrator( cost.function, ff.vol, ff.cost, mid.vol, mid.cost, cong.vol, cong.cost, result, max.depth, tol )
-}
-
-inner.integrator <- function( cost.function, ff.vol,ff.cost,mid.vol,mid.cost,cong.vol,cong.cost,result,depth, tol) {
- ivl <- (cong.vol-ff.vol)/4
- left.vol <- ff.vol + ivl
- left.cost <- cost.function(left.vol)
- right.vol <- cong.vol - ivl
- right.cost <- cost.function(right.vol)
- h.6 <- ivl/3
- result.left <- sum(h.6*(ff.cost+4*left.cost+mid.cost))
- result.right<- sum(h.6*(mid.cost+4*right.cost+cong.cost))
- result.2 <- result.left + result.right
- if ( depth<=0 || (abs(result.2-result)<=(tol*15)) ) { # if splitting doesn't improve result, return best guess
- result <- result.2 + (result.2-result)/15
- } else { # otherwise, process each half recursively seeking a better fit
- result <- Recall(cost.function,ff.vol,ff.cost,left.vol,left.cost,mid.vol,mid.cost,result.left,depth-1,tol/2)+
- Recall(cost.function,mid.vol,mid.cost,right.vol,right.cost,cong.vol,cong.cost,result.right,depth-1,tol/2)
- }
- result
- }
-
# Intercept Set, describes select link processing
# The intercept set is built at the level of the highway assignment
Added: pre-alpha/travelr/R/Cost_Integrator.R
===================================================================
--- pre-alpha/travelr/R/Cost_Integrator.R (rev 0)
+++ pre-alpha/travelr/R/Cost_Integrator.R 2010-05-05 01:50:40 UTC (rev 13)
@@ -0,0 +1,116 @@
+####################################################################################################
+# travelr\r\Cost_Integrator.R by Jeremy Raw Copyright (C) 2010
+#
+# The code for the two functions "cost.integrator" and "inner.integrator" was
+# adapted from Wikipedia. The text and code at Wikipedia are copyrighted and
+# distributed under the Creative Commons Share-Alike License 3.0, which is
+# available at http://creativecommons.org/licenses/by-sa/3.0/
+#
+# The Wikipedia code is additionally available (as the base code had not been
+# modified at Wikipedia since before June, 2009) under the terms of the GNU
+# Free Documentation License, available at
+# http://en.wikipedia.org/wiki/Wikipedia:GFDL
+#
+# Redistributing this code under the GNU General Public License, version 2.0
+# or later is likely to be unproblematic (YMMV, IANAL). Should additional
+# permissions or prohibitions be placed on the code under one of the above
+# licenses, the genesis of the code implies that the above licenses will take
+# precedence. It is recommended that this code be maintained in a separate
+# source code file, with this license text and copyright information intact.
+#
+####################################################################################################
+
+# The following comment block reproduces code from Wikipedia, accessed May 4, 2010
+# http://en.wikipedia.org/wiki/Adaptive_Simpson%27s_method
+#
+# From Wikipedia:
+# --------------------------------------------------------------------------------
+# Here is an implementation of the adaptive Simpson's method in C99 that avoids
+# redundant evaluations of f and quadrature computations, but also suffers from
+# memory runaway. Suggested improvement would be to use a for loop in
+# adaptiveSimpsonsAux:
+#
+# #include <math.h> // include file for fabs and sin
+# #include <stdio.h> // include file for printf
+#
+# //
+# // Recursive auxiliary function for adaptiveSimpsons() function below
+# //
+# double adaptiveSimpsonsAux(double (*f)(double), double a, double b, double epsilon,
+# double S, double fa, double fb, double fc, int bottom) {
+# double c = (a + b)/2, h = b - a;
+# double d = (a + c)/2, e = (c + b)/2;
+# double fd = f(d), fe = f(e);
+# double Sleft = (h/12)*(fa + 4*fd + fc);
+# double Sright = (h/12)*(fc + 4*fe + fb);
+# double S2 = Sleft + Sright;
+# if (bottom <= 0 || fabs(S2 - S) <= 15*epsilon)
+# return S2 + (S2 - S)/15;
+# return adaptiveSimpsonsAux(f, a, c, epsilon/2, Sleft, fa, fc, fd, bottom-1) +
+# adaptiveSimpsonsAux(f, c, b, epsilon/2, Sright, fc, fb, fe, bottom-1);
+# }
+#
+# //
+# // Adaptive Simpson's Rule
+# //
+# double adaptiveSimpsons(double (*f)(double), // ptr to function
+# double a, double b, // interval [a,b]
+# double epsilon, // error tolerance
+# int maxRecursionDepth) { // recursion cap
+# double c = (a + b)/2, h = b - a;
+# double fa = f(a), fb = f(b), fc = f(c);
+# double S = (h/6)*(fa + 4*fc + fb);
+# return adaptiveSimpsonsAux(f, a, b, epsilon, S, fa, fb, fc, maxRecursionDepth);
+# }
+#
+#
+# int main(){
+# double I = adaptiveSimpsons(sin, 0, 1, 0.000000001, 10); // compute integral of sin(x)
+# // from 0 to 1 and store it in
+# // the new variable I
+# printf("I = %lf\n",I); // print the result
+# return 0;
+# }
+# -----------------------------------------------------------------------------------
+# End of Wikipedia section
+#
+# The "runaway memory" problem could potentially be an issue in the R code, but
+# the Wikipedia-suggested solution of unrolling the recursion into a loop is
+# overkill if the cost function is well-behaved. Time and experience will tell
+# if we need to revisit this.
+
+# Note: cost.integrator can handle the special requirement that the volume and
+# cost parameters be vectors (and that the integral of the whole be the sum of
+# the integrals of each element from "free flow" volume (0) to the corresponding
+# element in "congested" volume). This function should also handle everything
+# happily even if ff.vol and cong.vol are data.frames or matrices.
+
+# The standard R 'integrate' function can't do any of that...
+
+cost.integrator <- function( cost.function, ff.vol, ff.cost, cong.vol, cong.cost, tol=1e-8, max.depth=14 ) {
+ # Integrate the cost function using adaptive quadrature with inside-interval tolerance testing
+ ivl <- (cong.vol-ff.vol)/2
+ mid.vol <- ff.vol+ivl
+ mid.cost <- cost.function(mid.vol)
+ result <- (ivl/3)*(ff.cost+4*mid.cost+cong.cost)
+ inner.integrator( cost.function, ff.vol, ff.cost, mid.vol, mid.cost, cong.vol, cong.cost, result, max.depth, tol )
+}
+
+inner.integrator <- function( cost.function, ff.vol,ff.cost,mid.vol,mid.cost,cong.vol,cong.cost,result,depth, tol) {
+ ivl <- (cong.vol-ff.vol)/4
+ left.vol <- ff.vol + ivl
+ left.cost <- cost.function(left.vol)
+ right.vol <- cong.vol - ivl
+ right.cost <- cost.function(right.vol)
+ h.6 <- ivl/3
+ result.left <- sum(h.6*(ff.cost+4*left.cost+mid.cost))
+ result.right<- sum(h.6*(mid.cost+4*right.cost+cong.cost))
+ result.2 <- result.left + result.right
+ if ( depth<=0 || (abs(result.2-result)<=(tol*15)) ) { # if splitting doesn't improve result, return best guess
+ result <- result.2 + (result.2-result)/15
+ } else { # otherwise, process each half recursively seeking a better fit
+ result <- Recall(cost.function,ff.vol,ff.cost,left.vol,left.cost,mid.vol,mid.cost,result.left,depth-1,tol/2)+
+ Recall(cost.function,mid.vol,mid.cost,right.vol,right.cost,cong.vol,cong.cost,result.right,depth-1,tol/2)
+ }
+ result
+}
Modified: pre-alpha/travelr/R/Highway_Assignment.R
===================================================================
--- pre-alpha/travelr/R/Highway_Assignment.R 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/R/Highway_Assignment.R 2010-05-05 01:50:40 UTC (rev 13)
@@ -64,7 +64,7 @@
# Note that some algorithms like MSA may provide alternate "global" defaults
control.defaults <- list(
- intercept=NULL,
+ intercept = NULL,
min.relative.gap = 1e-4, # stop if relative.gap goes below this value
max.iter = 100, # for MSA, it's overridden to 4 and other stopping conditions are ignored
# set max.iter=0 for open-ended running
Modified: pre-alpha/travelr/R/Path_Functions.R
===================================================================
--- pre-alpha/travelr/R/Path_Functions.R 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/R/Path_Functions.R 2010-05-05 01:50:40 UTC (rev 13)
@@ -24,7 +24,7 @@
.zero.base<-function(v) v-1
.one.base <-function(v) v+1
-.build.network.set <- function( network, link.subset, pen.subset=NULL ) {
+.build.network.set <- function( network, link.subset=NULL, pen.subset=NULL ) {
# Construct network structures for use in path building
# Note that for network subsets (e.g. a network without HOV lanes), the cost and volume vectors will still have
@@ -32,6 +32,7 @@
# the selected set will be inserted into the edge list and offsets for path-building.
# The correspondence to the base tables of links and penalties is through .LinkID and .PenaltyID
+ if (is.null(link.subset)) link.subset=TRUE
links<-network$Links[link.subset,]
Link.fields<-network$Link.fields
edges<-matrix( c(A=.zero.base(links[[Link.fields["From"]]]),
Modified: pre-alpha/travelr/man/assignment.class.Rd
===================================================================
--- pre-alpha/travelr/man/assignment.class.Rd 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/man/assignment.class.Rd 2010-05-05 01:50:40 UTC (rev 13)
@@ -1,3 +1,20 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Copyright (C) 2010 by Jeremy Raw
+% This program is free software; you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation; either version 2 of the License, or
+% (at your option) any later version.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+% GNU General Public License for more details.
+%
+% A copy of the GNU General Public License is available at
+% http://www.r-project.org/Licenses/
+% and included in the R distribution (in directory ‘share/licenses’).
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\name{assignment.class}
\alias{assignment.class}
\alias{make.assignment.class}
@@ -5,10 +22,10 @@
\alias{add.assignment.class.list}
\title{
-Managing individual highway assignment classes
+Building highway assignment classes
}
\description{
-Keep network variants and demand sets for use in multi-class highway assignment.
+These functions facilitate constructing network variants and demand sets for use in multi-class highway assignment.
}
\usage{
make.assignment.class(network, name, demand, link.subset=TRUE, penalty.subset=NULL, cost.function=NULL)
@@ -17,24 +34,24 @@
}
\arguments{
\item{network}{
- The base highway network on which this assignment set will be loaded.
+ The base highway network on which this assignment set will be loaded
}
\item{name}{
- A name (character string) for the assignment class.
+ A name (character string) for the assignment class
}
\item{demand}{
A demand matrix for the named assignment class
}
\item{link.subset}{
An index vector that can be used to select links in the base network that will be available for this assignment
- class.
+ class
}
\item{penalty.subset}{
An index vector that selects which penalties (from the network's turn penalty table) will be applied to this
- assignment set.
+ assignment set
}
\item{cost.function}{
- A function generating costs from volumes for the assignment set (optional if each assignment class has its own); see details
+ A \code{\link{cost.function}} for the class. Not required or recommend; see details
}
\item{classes}{
A list, either empty or containing previously added assignment classes
@@ -44,32 +61,42 @@
}
}
\details{
+These functions support multi-class \link{highway assignment}.
+
Use \code{make.assignment.class} to construct a new assignment class. Use \code{add.assignment.class} to add another
assignment class to a list of assignment classes. A list of assignment classes is required for the \code{classes} parameter
in \code{\link{new.assignment.set}}.
-It is common to have a non-null \code{link.subset}, with the most common situation being to distinguish networks in which
-all links are available from one that only contains links available to a certain vehicle class (e.g. trucks or high-occupancy
-vehicles). It is similarly useful to have a non-null \code{penalty.subset}, either for penalties that are only
-applicable during certain periods of the day, or that are only applicable to certain vehicle classes.
+It is common to have a non-null \code{link.subset}, with the most common situation being to distinguish networks in
+which all links are available from one that only contains links available to a certain vehicle class (e.g. trucks or
+high-occupancy vehicles). It is similarly useful to have a non-null \code{penalty.subset}, either for penalties that
+are only applicable during certain periods of the day, or that are only applicable to certain vehicle classes. Only the
+links and penalties in the indicated subset will be examined when building paths. Care should be taken that the
+terminal nodes (zones) all remain connnected when the particular subset is selected. The \pkg{igraph} package can be
+useful for rapidly testing connectivity. The shortest path functions will warn if the resulting network subset is not
+connected.
-The \code{cost.function} parameter should be supplied if the ultimate assignment set is expecting the cost function to
-vary by class (for example by applying a PCE correction to truck volumes when computing routing cost for passenger
-vehicles, but not applying the PCE to the routing cost for trucks themselves), or when certain classes are assigned to
-free-flow paths regardless of the level of congestion (effectively pre-loading the network with those vehicles). Note,
-however, that getting fancy with cost functions is not advised since it can wreak havoc with the convergence of
-equilibrium assignment algorithms, and the simplest possible cost function model should be sought. If a single cost
-function applies to all assignment classes, it is simpler and recommended to use a single cost function for the entire
-assignment set (and to supply it through \code{\link{new.assignment.set}}.
+The \code{cost.function} parameter is not used directly, but is provided as a convenience since it is sometimes
+desirable to decompose the \code{cost.function} for the \code{\link{assignment.set}} into smaller functions specifically
+for the individual classes. These can be called by the user's assignment set cost function. Getting fancy with cost
+functions is not advised since it can wreak havoc with the convergence of equilibrium assignment algorithms, and the
+simplest possible cost function model should be sought (which usually means providing a single function through
+\code{\link{new.assignment.set}}).
\code{add.assignment.class} is generic, and can add an assignment class to an \code{\link{assignment.set}} or to an
existing list of assignment classes previously created with \code{add.assignment.class}. It performs a variety of
-tests to ensure that the proposed assignment class has everythign it needs to operate successfully. Be very atttentive
-to how the \code{\link{cost.function}} is going to be applied by the assignment set.
+tests to ensure that the proposed assignment class has everythign it needs to operate successfully.
}
\value{
-\code{make.assignment.class} returns a list of elements with R class \code{highway.assignment.class} suitable for
-building a \code{\link{assignment.set}}
+\code{make.assignment.class} returns a list of elements with class \code{highway.assignment.class} suitable for
+building a \code{\link{assignment.set}}. The specific list elements are:
+\describe{
+ \item{name}{A unique name for the class, constructed according to the rules of legal names for \R symbols; see \code{\link{make.names}} for help in creating a good name}
+ \item{demand}{A demand matrix with demand for this class (e.g. trucks, or high-occupancy vehicles)}
+ \item{network.set}{The network topology, including turn penalties and open links, for this assignment class}
+ \item{cost.function}{A class-specific cost function; only called if specifically coded in the assignment set cost function}
+}
+
\code{add.assignment.class} returns its first argument, to which \code{aclass} has been added.
}
\author{
Modified: pre-alpha/travelr/man/assignment.functions.Rd
===================================================================
--- pre-alpha/travelr/man/assignment.functions.Rd 2010-05-04 01:07:40 UTC (rev 12)
+++ pre-alpha/travelr/man/assignment.functions.Rd 2010-05-05 01:50:40 UTC (rev 13)
@@ -1,11 +1,26 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Copyright (C) 2010 by Jeremy Raw
+% This program is free software; you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation; either version 2 of the License, or
+% (at your option) any later version.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+% GNU General Public License for more details.
+%
+% A copy of the GNU General Public License is available at
+% http://www.r-project.org/Licenses/
+% and included in the R distribution (in directory ‘share/licenses’).
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\name{Assignment Functions}
+\alias{assignment.functions}
\alias{build.convergence.test}
-\alias{build.general.objective.function}
\alias{build.equil.stats.function}
\alias{build.lambda.function}
\alias{build.lambda.search}
-\alias{cost.integrator}
-\alias{parse.control}
\alias{weighted.update}
\alias{weighted.update.diff}
\alias{weighted.update.intercept}
@@ -18,35 +33,23 @@
Generally, they are only of interest to developers implementing new assignment algorithms.
}
\usage{
-parse.control(control,control.element,default.value=NULL)
-
build.convergence.test(control,test=c("min.relative.gap","max.iter","max.elapsed"))
build.equil.stats.function(objective.function,flow=0)
build.lambda.function(aset)
build.lambda.search(lambda.func,opt.tol=.Machine$double.eps^0.25)
-build.general.objective.function(aset, ff.vol, ff.cost, tol = 1e-04, max.depth = 14)
-cost.integrator(cost.function,ff.vol,ff.cost,cong.vol,cong.cost,tol=1e-8,max.depth=14)
-
weighted.update(weight,base,new)
weighted.update.diff(weight,base,new.diff)
weighted.update.intercept(weight,base,new)
}
-%- maybe also 'usage' for other objects documented here.
\arguments{
\item{control}{
- Assignment algorithm control parameters
+ Assignment algorithm control parameters (a named list)
}
-\item{control.element}{
- Parameter to retrieve
-}
-\item{default.value}{
- Default value to supply if control parameter is not set (if NULL, global defaults apply)
-}
\item{test}{
Which control parameters indicate convergence criteria (parameter name must start with
\code{.min} or \code{.max} indicating how to test; the remainder of the name must match
- a value computed in the equilibrium stats function)
+ a value computed in the equilibrium statistics function; see details)
}
\item{objective.function}{
The objective function to be minimized during the equilibrium assignment process
@@ -54,9 +57,6 @@
\item{flow}{
The sum of all the demand matrices in the assignment set (used to compute average excess cost)
}
-\item{cost.function}{
- The cost function (volume/delay) that relates link volume to delay penalty
-}
\item{lambda.func}{
The function for which a zero is found to compute the optimum step size in a search direction
}
@@ -66,24 +66,9 @@
\item{aset}{
An \code{\link{assignment.set}} with a \code{\link{cost.function}}
}
-\item{ff.vol}{
- Free flow (or lower bound) volumes (vector or matrix depending on type of cost function)
-}
-\item{ff.cost}{
- Link costs corresponding to free-flow (or lower bound) volumes
-}
\item{tol}{
Convergence tolerance for cost function integration using adaptive quadrature
}
-\item{cong.vol}{
- Congested (or upper bound) volumes
-}
-\item{cong.cost}{
- Link costs corresponding to congested (or upper bound) volumes)
-}
-\item{max.depth}{
- Maximum allowed recursion level during cost integration (a maximum of \code{2^max.depth+1} calls to the cost function will be made)
-}
\item{weight}{
Weight of new values in computing weighted average of base and new
}
@@ -98,18 +83,94 @@
}
}
\details{
-Details on assignment functions are yet to come.
+These functions will generally only be of interest to the developers of new highway assignment algorithms.
+
+\code{parse.control} extracts a parameter from the \code{control} list typically provided to the
+\code{\link{highway.assign}} function. Certain parameters have global defaults, which may be overridden
+by a local default if the \code{default} parameter is supplied. The global defaults are as follows:
+\tabular{llll}{
+min.relative.gap\tab numeric\tab \code{1e-4} \tab Target for relative gap statistic \cr
+max.iter\tab numeric\tab \code{100} \tab Maximum iteration, except 4 for method=dQuote{\acronym{MSA}}) \cr
+max.elapsed\tab numeric \tab \code{3600} \tab seconds since the algorithm started \cr
+opt.tol\tab numeric \tab \code{.Machine$double.eps^0.5} \tab tolerance for internal line searches) \cr
+verbose\tab numeric \tab \code{1} \tab Debugging level (higher numbers may generate more output; 0 for silent) \cr
+log\tab logical \tab \code{FALSE} \tab If true, save a \code{data.frame} with the equilibrium statistics from each
+iteration
}
+Any parameter for which no default is provided will return \code{NULL} when requested.
+
+Arbitrary additional parameters may be defined. The \code{control} parameter is just a named list
+of values, and the function simply looks up the name and returns the corresponding element. It
+differs from simple list indexing in that it can provide a default value.
+
+Certain of these functions build other functions, tying certain fixed parameters into the function's
+environment in order to reduce the burden of redundant interpretation and computation during highway
+assignment.
+
+Perhaps the most obscure are the following:
+
+\code{build.equil.stats.function} builds a function that computes performance statistics for an iteration of
+the equilibrium assignment algorithm. The built function is defined as follows:
+\preformatted{
+ function(iter, cost, vol, diff, best.lower.bound=as.numeric(NA), extras=list())
+}
+\describe{
+ \item{iter}{The current iteration, numeric}
+ \item{cost}{The current cost structure (usually a \code{data.frame}; see \code{\link{cost.functions}})}
+ \item{vol}{The current volume structure (usually a \code{data.frame}; see \code{\link{load.paths}}) }
+ \item{diff}{A \code{data.frame} containing the difference between the most recent \acronym{AON} volume and the
+ current equilibrium volume}
+ \item{best.lower.bound}{The \code{best.lower.bound} as of the previous iteration, or \code{as.numeric(NA)} if
+ the first iteration}
+ \item{extras}{a named list of additional (scalar) values to be placed in the output list}
+}
+The standard equilibrium statistics function returns a list of computed statistics that can be compared against
+target values to assess the convergence of an assignment algorithm. The output includes:
+\describe{
+ \item{iter}{Current iteration, supplied as an input parameter}
+ \item{elapsed}{Time, in seconds, elapsed since the function was defined}
+ \item{objective}{Value of the objective function at the start of this iteration}
+ \item{gap}{Value of the \dQuote{gap} statistic}
+ \item{relative.gap}{Value of the \dQuote{relative gap} statistic}
+ \item{lower.bound}{Value of the \dQuote{lower bound} statistic}
+ \item{best.lower.bound}{The greatest of either the \code{best.lower.bound} parameter or the newly computed \code{lower.bound}}
+ \item{avg.excess.cost}{Value of the Average Excess Cost (normalized gap) statistic}
+ \item{extras}{Any values passed in through the \code{extras} parameter}
+}
+
+The \code{build.convergence.test} function returns a function that will compare the computed equilibrim statistics to target
+values supplied either through the \code{control} parameter for the \code{\link{highway.assign}} function, or as a default value
+through \code{parse.control}, or as a global default value.
+
+The general mechanism for constructing a test is to provide names in the \code{test} vector that match the names of
+values in the \code{control} list. Those names should begin either with \dQuote{\code{min.}} or \dQuote{\code{max.}}
+indicating how the equilibrium statistic will be compared. The name without the prefix should correspond to the name of
+a statistic in the result list from the equilibrium statistics function (including, possibly, a name in the
+\code{extras} list.
+
+The \code{highway.assign} source code provides examples of how to apply these functions.
+}
+
\value{
-Returns a highway.assignment.result object
+\code{parse.control} returns a value for the named highway assignment control parameter
+
+\code{build.convergence.test} returns a function that does a convergence test
+
+\code{build.equil.stats.function} returns a function that builds a list of assignment statistics for reporting and convergence testing
+
+\code{build.lambda.function} returns a function with a zero at a point of interest
+
+\code{build.lambda.search} returns a function that finds the zero of a lambda function given upper and lower limits
+
+\code{weighted.update} returns a value the same shape as its first argument that is the weighted average of its arguments
+
+\code{weighted.update.diff} returns a value the same shape as its first argument that is the first argument plus weight times its second argument
+
+\code{weighted.update.intercept} returns an \code{\link{intercept list}} (with two elements, \code{od} and \code{volumes}) that is the weighted average of the two intercept lists passed to it
}
\author{
Jeremy Raw
}
-
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/travelr -r 13
More information about the Travelr-commits
mailing list