UTN_UE.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/nagae/UrbanRoadNetworkAnalyses/blob/master/UTN_UE.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "J-EEfho5agMN"
      },
      "source": [
        "# User Equilibrium Assignment\n",
        "この `notebook` では，利用者均衡配分を Frank-Wolfe 法で解くためのアルゴリズムを解説する．\n",
        "\n",
        "(静的)***利用者均衡(*User Equilibrium*: UE)配分***とは，下記の3つの情報:\n",
        "- 道路ネットワーク構造\n",
        "- 各リンクの性能関数\n",
        "- 各起終点(OD: *origin-destination*)ペアの交通需要\n",
        "\n",
        "を与件として，\n",
        "\n",
        "> どの利用者についても，自分だけが経路を変更することではそれ以上交通費用を改善できない状態(フロー・パターン)\n",
        "\n",
        "と定義される．\n",
        "\n",
        "UEモデルおよびその解法の特徴的な点は，以下の2点である: \n",
        "\n",
        "1. 経路を明示的に考慮する必要のない，ノード/フロー変数のみで均衡条件を記述する．\n",
        "2. 均衡状態を求める問題が，凸計画問題に帰着することを活用する．\n",
        "\n",
        "これにより，リンク性能関数が特定の条件[<sup>1</sup>](#fn1)を満足するならば，ODペアが多起点・多終点で，リンクが数千本存在するような一般ネットワークに対しても，本 `notebook` で示す Frank-Wolfe 法によって，(そこそこ)効率的に均衡解が求められる．以下，UEモデルを簡単に解説し，その具体的解法を示そう．\n",
        "\n",
        "-----\n",
        "<span id=\"fn1\">[<sup>1</sup>]()リンク性能関数のJacobianが対称かつ半正定値であれば，本 `notebook` で示す解法が適用できる．</span>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "toc-hr-collapsed": false,
        "id": "Vfh1eYmyagMO"
      },
      "source": [
        "# User Equilbirium and Its Equivalent Convex Programming"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "YqPqfK2-agMP"
      },
      "source": [
        "## Road Network, Travel Demand, Link Performance and Path Cost\n",
        "\n",
        "道路ネットワークを有向グラフ(directed graph) $\\mathbb{G}(\\mathbb{N}, \\mathbb{L})$ で表す．\n",
        "\n",
        "ここで，$\\mathbb{L}$はリンク集合, $\\mathbb{N}$はノード集合である．以下では，ノード数を$N$, リンク数を$L$で表す．\n",
        "\n",
        "交通需要の起点ノードおよび終点ノードの集合[<span>2</span>](#fn2)を, それぞれ, $\\mathbb{O}, \\mathbb{D} \\subseteq \\mathbb{N}$で表し，\n",
        "\n",
        "起終点ペアの集合を$\\mathbb{W} = \\mathbb{O}\\times\\mathbb{D}$で表し，その要素数を$W$で表す．\n",
        "\n",
        "起終点ペア$(r,s) \\in \\mathbb{W}$の交通需要を，所与の定数$q^{rs}$で表す．\n",
        "\n",
        "  \n",
        "\n",
        "道路ネットワークの構造は，ノード-リンク接続行列$\\mathbf{A}$で表される．この行列の次元は$N\\times L$であり，その$n$行$ij$列要素$a_{n, ij}$が\n",
        "\n",
        "$$\n",
        "a_{n, ij} = \\begin{cases}\n",
        "1 & \\text{if $n=i$ (node $n$ is the upstream of link $ij$)} \\\\\n",
        "-1 & \\text{if $n=j$ (node $n$ is the downstream of link $ij$}) \\\\\n",
        "0 & \\text{otherwise}\n",
        "\\end{cases}\n",
        "$$\n",
        "\n",
        "で定義される．\n",
        "\n",
        "  \n",
        "\n",
        "起終点ペア$(r,s) \\in \\mathbb{W}$に対する経路集合を$\\mathbb{K}^{rs}$で表し，その要素数を$K^{rs}$で表す．経路$k \\in \\mathbb{K}^{rs}$上の単位時間あたり交通量\\[台/分\\]を **経路$k$のフロー** (path flow) と呼び，$f_{k}^{rs}$で表す．ベクトル$\\mathbf{f}=\\left\\{f_{k}^{rs} : k \\in \\mathbb{K}^{rs}, (r,s) \\in \\mathbb{W}\\right\\}$ を経路フローと呼び，その次元を$K = \\sum_{rs\\in\\mathbb{W}}K^{rs}$ で表す．経路フローは，以下のフロー保存則と非負制約を満足する時，**実行可能(feasible)である**という:\n",
        "\n",
        "$$\\begin{cases}\n",
        "\\sum_{k \\in \\mathbb{K}^{rs}} f_{k}^{rs} = q^{rs}\\\\\n",
        "f_{k}^{rs} \\geq 0, \\quad \\forall k \\in \\mathbb{K}^{rs}\n",
        "\\end{cases},\n",
        "\\qquad \\forall (r, s) \\in \\mathbb{W}$$\n",
        "\n",
        "リンク$(i,j)$上の単位時間あたり交通量\\[台/分\\]を **リンク$(i,j)$のフロー** (link flow)と呼び，$x_{ij}$で表す. ベクトル$\\mathbf{x} = \\left\\{x_{ij}: (i, j) \\in \\mathbb{L}\\right\\}$をリンク・フローと呼ぶ．\n",
        "\n",
        "経路フロー$\\mathbf{f}$とリンク・フロー$\\mathbf{x}$の間には，以下の関係が成立する:\n",
        "\n",
        "$$\n",
        "\\mathbf{x} = \\mathbf{\\Delta} \\mathbf{f}.\n",
        "$$\n",
        "\n",
        "ここで，$\\mathbf{\\Delta}$は，その次元が$L\\times{}K$であり，その$ij$行$krs$列要素$\\delta_{ij, k}^{rs}$が，以下の Kronecker's delta で表される:\n",
        "\n",
        "$$\n",
        "\\delta_{ij, k}^{rs} = \\begin{cases}\n",
        "1 & \\text{if link $ij$ is on path $k$ of O-D pair $rs$} \\\\\n",
        "0 & \\text{otherwise}\n",
        "\\end{cases}\n",
        "$$\n",
        "\n",
        "上式は，下記のように要素表示することもできる:\n",
        "\n",
        "$$\n",
        "x_{ij} = \\sum_{(r,s) \\in \\mathbb{W}} \\sum_{k \\in \\mathbb{K}^{rs}} \\delta_{ij, k}^{rs} f_{k}^{rs}\n",
        "$$\n",
        "\n",
        "  \n",
        "\n",
        "フローに依存するリンク$(i, j)$の交通費用を，当該リンク・フローの非減少関数$t_{ij}(x_{ij})$で表し，**リンク$(i, j)$の性能関数** (performance function)と呼ぶ．交通工学分野で用いられる代表的なリンク性能関数として, 以下のBPR (*Bureau of Public Roads*)型が挙げられる:\n",
        "\n",
        "$$t_{ij}(x_{ij}) = t_{0, ij}\\left\\{1 + \\beta\\left(\\frac{x_{ij}}{\\mu_{ij}}\\right)^{\\gamma}\\right\\}$$\n",
        "\n",
        "- $t_{0, ij}$ : リンク$(i, j)$の自由走行時間\\[分\\]\n",
        "- $\\mu_{ij}$ : リンク$(i, j)$の道路容量\\[台/分\\] (単位時間あたりに通過可能な台数)\n",
        "- $\\beta, \\gamma$ : パラメータ．ただし，$\\beta \\geq 0$, $\\gamma \\geq 1$.\n",
        "\n",
        "リンクの交通費用が$\\mathbf{t} = \\left\\{t_{ij}: (i, j) \\in \\mathbb{L}\\right\\}$である時，起終点ペア$(r, s) \\in \\mathbb{W}$ の経路$k \\in \\mathbb{K}^{rs}$の費用は\n",
        "\n",
        "$$\n",
        "C_{k}^{rs} = \\sum_{(i, j) \\in \\mathbb{L}} \\delta_{ij, k}^{r} t_{ij}\n",
        "$$\n",
        "\n",
        "と表せる．経路費用ベクトルを$\\mathbf{C} = \\left\\{C_{k}^{rs}: k \\in \\mathbb{K}^{rs}, (r, s) \\in \\mathbb{W}\\right\\}$と表す時，上式は\n",
        "\n",
        "$$\n",
        "\\mathbf{C} = \\mathbf{\\Delta}^{\\top} \\mathbf{t}\n",
        "$$\n",
        "\n",
        "とも表現できる．\n",
        "\n",
        "\n",
        "-----\n",
        "<span>[<sup>2</sup>]() 実際の交通需要は道路ネットワーク上に実在する特定の物理的なノードで発生/集中する訳ではないため，需要が発生/集中する仮想的なノードを設けるのが一般的である．このため，物理的な道路ネットワーク上の通過ノードと区別するために，起点/終点ノードを **ゾーン** と呼ぶこともある．</span>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pgLSC2g4agMP"
      },
      "source": [
        "## User Equilibrium\n",
        "\n",
        "経路フロー$\\mathbf{f}$に対する経路交通費用$\\mathbf{C}(\\mathbf{f})$を，以下の関数で表す:\n",
        "\n",
        "$$\n",
        "\\mathbf{C}(\\mathbf{f}) = \\mathbf{\\Delta}^{\\top} \\mathbf{t}\\left(\\mathbf{\\Delta} \\mathbf{f}\\right)\n",
        "$$\n",
        "\n",
        "  \n",
        "\n",
        "実行可能な経路フロー$\\mathbf{f}$は，下記を満足する時，**利用者均衡(UE)状態** であると言う:\n",
        "> 任意の起終点ペアについて，どの利用者も，自分だけが経路を変更することではそれ以上経路費用を改善できない状態．\n",
        "\n",
        "  \n",
        "\n",
        "均衡状態においては，明らかに，以下の **Wardrop原則** が成立する:\n",
        "> 任意の起終点ペアについて，利用されている経路の費用はいずれも等しく，利用されていない経路の費用がそれを下回ることはない．\n",
        "\n",
        "  \n",
        "\n",
        "均衡経路フローを$\\mathbf{f}^{\\ast} = \\{f_{k}^{\\ast rs}\\}$ で表し，起終点ペア$(r, s)$の最小費用(**均衡費用(equilibrium cost)** と呼ぶ)を\n",
        "$$\n",
        "\\rho^{\\ast rs} = \\min_{k \\in \\mathbb{K}^{rs}} C_{k}^{rs}(\\mathbf{f}^{\\ast})\n",
        "$$\n",
        "\n",
        "で表す時，上記Wardrop原則は以下の **相補性条件(complimentarity condition)** として記述できる:\n",
        "$$\n",
        "\\begin{cases}\n",
        "f_{k}^{\\ast rs} > 0 &\\rightarrow C_{k}^{rs}(\\mathbf{f}^{\\ast}) = \\rho^{\\ast rs} \\\\\n",
        "f_{k}^{\\ast rs} < 0 &\\leftarrow C_{k}^{rs}(\\mathbf{f}^{\\ast}) > \\rho^{\\ast rs}\n",
        "\\end{cases}\n",
        "\\quad \\forall k \\in \\mathbb{K}^{rs}, \\forall (r, s) \\in \\mathbb{W}\n",
        "$$\n",
        "\n",
        "この条件は，以下のように1行にまとめて記述することもできる:\n",
        "$$\n",
        "0 \\leq f_{k}^{\\ast rs} \\bot \\left\\{C_{k}^{rs}(\\mathbf{f}^{\\ast}) - \\rho^{\\ast rs}\\right\\} \\geq 0,\n",
        "\\qquad \\forall k \\in \\mathbb{K}^{rs}, \\forall (r,s) \\in \\mathbb{W}\n",
        "$$\n",
        "ここで，$0 \\leq a \\bot b \\geq 0$ は，$a \\geq 0, b \\geq 0$ かつ $ab = 0$ であることを表している．\n",
        "\n",
        "上記の最適経路選択条件と経路フローの実行可能性条件を，合わせて以下の相補性条件として記述しておくと便利である:\n",
        "$$\n",
        "\\begin{align}\n",
        "0 \\leq f_{k}^{\\ast rs} &\\bot \\left\\{C_{k}^{rs}(\\mathbf{f}^{\\ast}) - \\rho^{\\ast rs}\\right\\} \\geq 0, && \\forall k \\in \\mathbb{K}^{rs}, \\forall (r,s) \\in \\mathbb{W}\\\\\n",
        "0 \\leq \\rho^{\\ast rs} &\\bot \\left\\{q^{rs} - \\sum_{k \\in \\mathbb{K}^{rs}} f_{k}^{\\ast rs} \\right\\}\\geq 0, && \\forall (r,s) \\in \\mathbb{W}\n",
        "\\end{align}\n",
        "$$\n",
        " \n",
        "\n",
        "こうして相補性条件として記述された利用者均衡条件は，下記の凸計画問題の最適性(KKT: *Karush-Kuhn-Tucker*)条件と等価である：\n",
        "$$\n",
        "\\begin{alignat}{3}\n",
        "\\text{[P-path]} \\qquad \\min_{\\mathbf{f}} \\quad &\n",
        "Z(\\mathbf{x}(\\mathbf{f})) :=\n",
        "\\sum_{(i, j) \\in \\mathbb{L}}\n",
        "\\int_{0}^{x_{ij}(\\mathbf{f})} t_{ij}(\\omega) \\mathrm{d}\\omega\n",
        "\\\\\n",
        "\\text{Sub to.} \\quad\n",
        "&\\sum_{k \\in \\mathbb{K}^{rs}} f_{k}^{rs} = q^{rs} , \\quad \\forall (r, s) \\in \\mathbb{W}, \\\\\n",
        "&f_{k}^{r, s} \\geq 0, \\quad \\forall k \\in \\mathbb{K}^{rs}, \\forall (r, s) \\in \\mathbb{W}\n",
        "\\end{alignat}\n",
        "$$\n",
        "ただし，$x_{ij}(\\mathbf{f}) = \\sum_{(r, s) \\in \\mathbb{W}} \\sum_{k \\in \\mathbb{K}^{rs}} \\delta_{ij, k}^{rs} f_{k}^{rs}$(i.e. $\\mathbf{x}(\\mathbf{f}) = \\mathbf{\\Delta} \\mathbf{f}$) である．\n",
        "\n",
        "\n",
        "具体的には，\\[P\\]のフロー保存則$\\sum_{k \\in \\mathbb{K}^{rs}} f_{k}^{rs} = q^{rs}$ に対応する双対変数を $\\rho^{rs}$ とし，$\\boldsymbol{\\rho} = \\{\\rho^{rs}: (r, s) \\in \\mathbb{W}\\}$ として Lagrangian を\n",
        "$$\n",
        "L(\\mathbf{f}, \\boldsymbol{\\rho}) = Z(\\mathbf{x}(\\mathbf{f})) +\n",
        "\\sum_{(r, s) \\in \\mathbb{W}} \\rho^{rs} \\left\\{ q^{rs} - \\sum_{k \\in \\mathbb{K}^{rs} } f_{k}^{rs}\\right\\}\n",
        "$$\n",
        "と定義すれば，\n",
        "\n",
        "$$\n",
        "\\begin{align}\n",
        "\\frac{\\partial L}{\\partial f_{k}^{rs}} &= \\sum_{(i, j) \\in \\mathbb{L}} \\frac{\\partial Z}{\\partial x_{ij}} \\frac{\\partial x_{ij}}{\\partial f_{k}^{rs}} - \\rho^{rs} = \\sum_{(i, j) \\in \\mathbb{L}} t_{ij}\\left(x_{ij}(\\mathbf{f})\\right) \\delta_{ij, k}^{rs} - \\rho^{rs}\n",
        "= C_{k}^{rs}(\\mathbf{f}) - \\rho^{rs}\n",
        "\\\\\n",
        "\\frac{\\partial L}{\\partial \\rho^{rs}} &= q^{rs} - \\sum_{k \\in \\mathbb{K}^{rs}} f_{k}^{rs}\n",
        "\\end{align}\n",
        "$$\n",
        "より，問題\\[P-path\\]の最適性条件\n",
        "$$\n",
        "\\begin{align}\n",
        "0 \\leq f_{k}^{rs} &\\bot \\frac{\\partial L}{\\partial f_{k}^{rs}} \\geq 0 && \\forall k \\in \\mathbb{K}^{rs}, \\forall (r,s) \\in \\mathbb{W}\\\\\n",
        "0 \\leq \\rho^{rs} &\\bot \\frac{\\partial L}{\\partial \\rho^{rs}} \\geq 0 && \\forall (r,s) \\in \\mathbb{W}\n",
        "\\end{align}\n",
        "$$\n",
        "が，相補性条件として記述された均衡条件と等価であることが容易に確認できる．"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3AYIT_xCagMQ"
      },
      "source": [
        "結局のところ，利用者均衡配分問題は，以下の(起点別)リンク変数のみを未知変数とした凸計画問題に帰着する:\n",
        "$$\n",
        "\\begin{alignat}{3}\n",
        "\\text{[P]} \\qquad \n",
        "\\min_{\\mathbf{x}} &Z(\\mathbf{x}) := \\sum_{ij \\in \\mathbb{L}} \\int_{0}^{x_{ij}} t_{ij}(\\omega) \\mathrm{d}\\omega\\\\ \n",
        "\\text{Sub to}\\quad &\n",
        "\\sum_{ni \\in \\mathbb{L}} x_{ni}^{r} - \\sum_{im \\in \\mathbb{L}} x_{im}^{r} = \n",
        "q^{ri} \\quad && \\forall i \\in \\mathbb{N}_{-r}, \\forall r \\in \\mathbb{N} \\\\\n",
        "& x_{ij} = \\sum_{r \\in \\mathbb{N}} x_{ij}^{r} && \\forall ij \\in \\mathbb{L} \\\\\n",
        "& x_{ij}^{r} \\geq 0 && \\forall ij \\in \\mathbb{L}, \\forall r \\in \\mathbb{N}\n",
        "\\end{alignat}\n",
        "$$"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LCvuPedAagMQ"
      },
      "source": [
        "結局のところ，利用者均衡配分問題は，以下の(起点別)リンク変数のみを未知変数とした凸計画問題に帰着する:\n",
        "$$\n",
        "\\begin{alignat}{3}\n",
        "\\text{[P]} \\qquad \n",
        "\\min_{\\mathbf{x}} &Z(\\mathbf{x}) := \\sum_{ij \\in \\mathbb{L}} \\int_{0}^{x_{ij}} t_{ij}(\\omega) \\mathrm{d}\\omega\\\\ \n",
        "\\text{Sub to}\\quad &\n",
        "\\sum_{ni \\in \\mathbb{L}} x_{ni}^{r} - \\sum_{im \\in \\mathbb{L}} x_{im}^{r} = \n",
        "q^{ri} \\quad && \\forall i \\in \\mathbb{N}_{-r}, \\forall r \\in \\mathbb{N} \\\\\n",
        "& x_{ij} = \\sum_{r \\in \\mathbb{N}} x_{ij}^{r} && \\forall ij \\in \\mathbb{L} \\\\\n",
        "& x_{ij}^{r} \\geq 0 && \\forall ij \\in \\mathbb{L}, \\forall r \\in \\mathbb{N}\n",
        "\\end{alignat}\n",
        "$$"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "P6XjG2r-agMQ"
      },
      "source": [
        "# Frank-Wolfe Method for Solving The Equivalent Convex Programming\n",
        "等価最適化問題\\[P\\]は，Frank-Wolfe法と呼ばれるアルゴリズムを用いて解くことができる．この方法は，許容領域(非負制約とフロー保存則が満足される)の中で，下記の2つのステップを繰返すことで目的関数がより小さくなるように解を改訂し，最適化問題の解(i.e. 均衡配分)を求める．\n",
        "1. 等価最適化問題の目的関数が小さくなる方向(降下方向)を求める．\n",
        "2. 降下方向に沿った移動量(ステップ・サイズ)を求め，解を改訂する．"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "hTIBmefaagMQ"
      },
      "source": [
        "## Auxiliary Problem and Descent Direction\n",
        "いま，$n$番目繰返しにおける暫定解(配分)を$\\mathbf{x}^{(n)}$で表し，$Z^{(n)} = Z(\\mathbf{x}^{(n)})$ としよう．この暫定解の周りで[P]の目的関数$Z(\\mathbf{x})$を線形近似したものは，\n",
        "$$\n",
        "Z(\\mathbf{y}) \\approx Z^{(n)} + {\\nabla Z(\\mathbf{x}^{(n)})}^{\\top}\\left( \\mathbf{y} - \\mathbf{x}^{(n)}\\right)\n",
        "$$\n",
        "と表せる．ここで，$\\nabla Z(\\mathbf{x}^{(n)}) = \\left(\\frac{\\partial Z}{\\partial x_{ij}^{r}}(\\mathbf{x}^{(n)})\\right)$ は，目的関数の勾配ベクトルを表す．\n",
        "\n",
        "ここで $\\frac{\\partial Z}{\\partial x_{ij}^{r}}(\\mathbf{x}^{(n)}) = t_{ij}(x_{ij}^{(n)}) = t_{ij}^{(n)}$ と書くことにすれば，許容領域の中で線形近似された目的関数を最小化させる配分$\\mathbf{y}$は，以下の線形計画問題(**補助問題**と呼ぶ)の解として得られる:\n",
        "$$\n",
        "\\begin{alignat}{3}\n",
        "\\text{[AP]} \\qquad \n",
        "\\min_{\\mathbf{x}} &\\sum_{r \\in \\mathbb{N}} \\sum_{ij \\in \\mathbb{L}} t_{ij}^{(n)} y_{ij}^{r} \\\\ \n",
        "\\text{Sub to}\\quad &\n",
        "\\sum_{ni \\in \\mathbb{L}} y_{ni}^{r} - \\sum_{im \\in \\mathbb{L}} y_{im}^{r} = \n",
        "q^{ri} \\quad && \\forall i \\in \\mathbb{N}_{-r}, \\forall r \\in \\mathbb{N} \\\\\n",
        "& y_{ij}^{r} \\geq 0 && \\forall ij \\in \\mathbb{L}, \\forall r \\in \\mathbb{N}\n",
        "\\end{alignat}\n",
        "$$\n",
        "\n",
        "ここで，補助問題[AP]は AoN (*all-or-nothing*)配分問題となっていることに注意されたい．すなわち，各起点$r$について，各終点$i \\in \\mathbb{N}_{-r}$への最短経路上に全ての交通量$q^{ri}$を配分したものが[AP]の解となる．\n",
        "\n",
        "こうして得られた補助問題の解(**補助解**と呼ぶ)を$\\mathbf{y}^{(n)}$ と書き，現在の暫定解との差$\\mathbf{d}^{(n)} = \\mathbf{y}^{(n)} - \\mathbf{x}^{(n)}$ を**降下方向**と呼ぶ．"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "GwEk5UT_agMQ"
      },
      "source": [
        "## Auxiliary Problem and Descent Direction\n",
        "いま，$n$番目繰返しにおける暫定解(配分)を$\\mathbf{x}^{(n)}$で表し，$Z^{(n)} = Z(\\mathbf{x}^{(n)})$ としよう．この暫定解の周りで[P]の目的関数$Z(\\mathbf{x})$を線形近似したものは，\n",
        "$$\n",
        "Z(\\mathbf{y}) \\approx Z^{(n)} + {\\nabla Z(\\mathbf{x}^{(n)})}^{\\top}\\left( \\mathbf{y} - \\mathbf{x}^{(n)}\\right)\n",
        "$$\n",
        "と表せる．ここで，$\\nabla Z(\\mathbf{x}^{(n)}) = \\left(\\frac{\\partial Z}{\\partial x_{ij}^{r}}(\\mathbf{x}^{(n)})\\right)$ は，目的関数の勾配ベクトルを表す．\n",
        "\n",
        "ここで $\\frac{\\partial Z}{\\partial x_{ij}^{r}}(\\mathbf{x}^{(n)}) = t_{ij}(x_{ij}^{(n)}) = t_{ij}^{(n)}$ と書くことにすれば，許容領域の中で線形近似された目的関数を最小化させる配分$\\mathbf{y}$は，以下の線形計画問題(**補助問題**と呼ぶ)の解として得られる:\n",
        "$$\n",
        "\\begin{alignat}{3}\n",
        "\\text{[AP]} \\qquad \n",
        "\\min_{\\mathbf{x}} &\\sum_{r \\in \\mathbb{N}} \\sum_{ij \\in \\mathbb{L}} t_{ij}^{(n)} y_{ij}^{r} \\\\ \n",
        "\\text{Sub to}\\quad &\n",
        "\\sum_{ni \\in \\mathbb{L}} y_{ni}^{r} - \\sum_{im \\in \\mathbb{L}} y_{im}^{r} = \n",
        "q^{ri} \\quad && \\forall i \\in \\mathbb{N}_{-r}, \\forall r \\in \\mathbb{N} \\\\\n",
        "& y_{ij}^{r} \\geq 0 && \\forall ij \\in \\mathbb{L}, \\forall r \\in \\mathbb{N}\n",
        "\\end{alignat}\n",
        "$$\n",
        "\n",
        "ここで，補助問題[AP]は AoN (*all-or-nothing*)配分問題となっていることに注意されたい．すなわち，各起点$r$について，各終点$i \\in \\mathbb{N}_{-r}$への最短経路上に全ての交通量$q^{ri}$を配分したものが[AP]の解となる．\n",
        "\n",
        "こうして得られた補助問題の解(**補助解**と呼ぶ)を$\\mathbf{y}^{(n)}$ と書き，現在の暫定解との差$\\mathbf{d}^{(n)} = \\mathbf{y}^{(n)} - \\mathbf{x}^{(n)}$ を**降下方向**と呼ぶ．"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "DjMDUhvvagMR"
      },
      "source": [
        "## Convergion Test\n",
        "Frank-Wolfe法では，上述の2つの手続き---補助問題の求解, ステップ・サイズの決定---を，均衡解が求められるまで繰返す．\n",
        "手続きを繰返すほど，より均衡解に近い暫定解が得られることが保証されるが，一般的には，暫定解が適当な収束条件を満足した時点で停止させる．\n",
        "代表的な収束条件として，以下の3つを挙げておく．ただし，以下では，$\\epsilon$ を十分に小さい定数とする．：\n",
        "\n",
        "1. 目的関数の変化率  \n",
        "  $n$回目繰返しにおける等価最適化問題の目的関数値を$Z^{(n)}$ と記述する時，\n",
        "  $$\\frac{Z^{(n-1)} - Z^{(n)}}{Z^{(n-1)}} \\leq \\epsilon$$\n",
        "  が満たされれば収束と判定.\n",
        "  \n",
        "2. リンクフローの変化率\n",
        "  $n$回目繰返しにおけるリンクフローを$x_{ij}^{(n)}$ と記述する時，\n",
        "  $$\\frac{\\sqrt{\n",
        "  \\sum_{ij \\in \\mathbb{L}}\n",
        "  \\left(x_{ij}^{(n)} - x_{ij}^{(n-1)}\\right)^{2}\n",
        "  }\n",
        "  }\n",
        "  {\\sum_{ij} x_{ij}^{(n-1)}} \\leq \\epsilon$$\n",
        "  が満たされれば収束と判定.\n",
        "  \n",
        "3. 各起終点間の最小交通費用の変化率\n",
        "  $n$回目繰返しにおける，起点$r$からノード$i(\\ne r)$への最小交通費用を$\\pi_{i}^{r(n)}$ と記述する時,\n",
        "  $$\n",
        "  \\sum_{rs \\in \\mathbb{W}}\n",
        "  \\frac{\\left|\n",
        "  \\pi_{i}^{r(n)} - \\pi_{i}^{r(n-1)}\n",
        "  \\right|\n",
        "  }\n",
        "  {\\pi_{i}^{r(n-1)}} \\leq \\epsilon$$\n",
        "  が満たされれば収束と判定.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "J0bD5aPtagMR"
      },
      "source": [
        "# Python Implementation\n",
        "上述の手法を，Pythonで実装してみよう．与えるネットワーク/交通需要データは [https://github.com/bstabler/TransportationNetworks](https://github.com/bstabler/TransportationNetworks) で公開されているものを用いる．\n",
        "データの読み取りは若干テクニカルなので，ここでは本教材用の実装済モジュール `TNTP` を使ってしまおう．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "WWIXw1QEagMR",
        "outputId": "b92c807d-7a96-4b2d-bd86-ec05b0c231b5"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "--2023-05-31 01:36:43--  https://raw.githubusercontent.com/nagae/UrbanRoadNetworkAnalyses/master/TNTP.py\n",
            "Resolving raw.githubusercontent.com (raw.githubusercontent.com)... 185.199.108.133, 185.199.109.133, 185.199.110.133, ...\n",
            "Connecting to raw.githubusercontent.com (raw.githubusercontent.com)|185.199.108.133|:443... connected.\n",
            "HTTP request sent, awaiting response... 200 OK\n",
            "Length: 9230 (9.0K) [text/plain]\n",
            "Saving to: ‘TNTP.py.3’\n",
            "\n",
            "\rTNTP.py.3             0%[                    ]       0  --.-KB/s               \rTNTP.py.3           100%[===================>]   9.01K  --.-KB/s    in 0s      \n",
            "\n",
            "2023-05-31 01:36:43 (51.6 MB/s) - ‘TNTP.py.3’ saved [9230/9230]\n",
            "\n",
            "fatal: destination path 'data' already exists and is not an empty directory.\n",
            "net file:\tdata/SiouxFalls/SiouxFalls_net.tntp\n",
            "trips file:\tdata/SiouxFalls/SiouxFalls_trips.tntp\n"
          ]
        }
      ],
      "source": [
        "!wget \"https://raw.githubusercontent.com/nagae/UrbanRoadNetworkAnalyses/master/TNTP.py\"\n",
        "!git clone https://github.com/bstabler/TransportationNetworks.git data\n",
        "import numpy as np\n",
        "import scipy as sp\n",
        "from scipy import sparse\n",
        "from operator import itemgetter, attrgetter\n",
        "from IPython.lib.pretty import pprint\n",
        "import TNTP # \n",
        "import importlib\n",
        "importlib.reload(TNTP)\n",
        "root = 'data' # データフォルダのルート\n",
        "dir_name = 'SiouxFalls' # ネットワーク・データの格納されたフォルダ名\n",
        "ntw = TNTP.Network(root, dir_name)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zvS2HmR3agMS"
      },
      "source": [
        "## `TNTP` Module and `Network` class\n",
        "上記のコードを実行すると, Network型のインスタンス `ntw` が生成される．この `ntw` は以下のメンバ変数を持つ:\n",
        "- `links_bn` : `_net.tntp` に記載されているリンクのリスト\n",
        "- `nodes_bn` : `links_bn` に登場するノード番号を昇順に並べたリスト．途中で欠番がある可能性もある．\n",
        "- `nid_of` : `nodes_bn` のノード番号を0から始まるリストのインデックスに対応させる辞書(`nid_of[1]`は1番ノードのリスト・インデックス)．\n",
        "- `nodes` : ノード集合(`nodes_bn` 0から始まる連続した整数のインデックス)\n",
        "- `links` : `links_bn` のノード番号を `nodes` に対応したインデックスに置き換えたもの\n",
        "- 'lid_of' : 'links' のノード・インデックス・ペアをリンクのインデックスに対応させる辞書\n",
        "- `fftt` : 各リンクの自由走行時間\\[分\\](`float`型の`numpy.array`)\n",
        "- `capacity` : 各リンクの容量\\[台/分\\](`float`型の`numpy.array`)\n",
        "- `b` : 各リンクのBPR関数の$\\beta$ (`float`型の`numpy.array`)\n",
        "- `power` : 各リンクのBPR関数の$\\gamma$ (`float`型の`numpy.array`)\n",
        "\n",
        "さらに，メンバ関数として以下を持つ：\n",
        "\n",
        "- `t(x)` : リンク数次元のnp.array型ベクトルを引数として，同次元のリンク費用(BPR関数)を返す\n",
        "- `t_mat(x)` : `t(x)`で得られるリンク費用を`sparse.csr_matrix`型の行列で返す(最短経路探索に利用)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "hwSannWCagMS",
        "outputId": "55dad4aa-266f-4f5b-b5e2-7547f8e54146"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "((1, 2),\n",
            " (1, 3),\n",
            " (2, 1),\n",
            " (2, 6),\n",
            " (3, 1),\n",
            " (3, 4),\n",
            " (3, 12),\n",
            " (4, 3),\n",
            " (4, 5),\n",
            " (4, 11),\n",
            " ...)\n"
          ]
        }
      ],
      "source": [
        "# リンクのリスト\n",
        "pprint(ntw.links_bn, max_seq_length=10)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "_MzqIn0tagMS"
      },
      "source": [
        "## Equivalent Convex Programming\n",
        "利用者均衡配分問題の等価最適化問題\\[P\\]の目的関数:\n",
        "$$\n",
        "Z(\\mathbf{x}) := \\sum_{ij \\in \\mathbb{L}} \\int_{0}^{x_{ij}} t_{ij}(\\omega) \\mathrm{d}\\omega\n",
        "$$\n",
        "を求めるためには，リンク性能関数の積分$T_{ij}(x_{ij}) = \\int_{0}^{x_{ij}} t_{ij}(\\omega) \\mathrm{d}\\omega$ を求める必要がある．リンク性能関数がBPR関数$t_{ij}(x_{ij}) = t_{0,ij}\\left\\{1 + \\beta(x_{ij}/\\mu_{ij})^{\\gamma}\\right\\}$ である場合，\n",
        "$$\n",
        "T_{ij}(x) = t_{0,ij} x_{ij} \\left\\{1 + \\frac{\\beta}{1+\\gamma}\\left(\\frac{x_{ij}}{\\mu_{ij}}\\right)^{\\gamma}\\right\\}\n",
        "$$\n",
        "である．$T_{ij}(x)$は手計算でも求められるが，以下のように `sympy` を用いて求めることもできる："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {
        "id": "qBP0f8cHagMS"
      },
      "outputs": [],
      "source": [
        "import sympy # import symbolic math module\n",
        "x, t0, mu, beta, gamma = sympy.symbols(('x', 't0', 'mu', 'beta', 'gamma')) # define unknowns\n",
        "t = t0*(1+beta*(x/mu)**gamma) \n",
        "T = sympy.simplify(sympy.integrate(t, x)) # intergrate the link performance tij function w.r.t. x"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 164
        },
        "id": "mZJtHm7sagMS",
        "outputId": "34d4928f-c598-47f4-f150-bc2dff8ff0c8"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "T:\n"
          ]
        },
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "Piecewise((t0*x*(beta*(x/mu)**gamma + gamma + 1)/(gamma + 1), (gamma > -1) | (gamma < -1)), (t0*(beta*mu*log(x) + x), True))"
            ],
            "text/latex": "$\\displaystyle \\begin{cases} \\frac{t_{0} x \\left(\\beta \\left(\\frac{x}{\\mu}\\right)^{\\gamma} + \\gamma + 1\\right)}{\\gamma + 1} & \\text{for}\\: \\gamma > -1 \\vee \\gamma < -1 \\\\t_{0} \\left(\\beta \\mu \\log{\\left(x \\right)} + x\\right) & \\text{otherwise} \\end{cases}$"
          },
          "metadata": {}
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "t (reproduced by differentiating T):\n"
          ]
        },
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "Piecewise((t0*(beta*(x/mu)**gamma + 1), (gamma > -1) | (gamma < -1)), (t0*(beta*mu + x)/x, True))"
            ],
            "text/latex": "$\\displaystyle \\begin{cases} t_{0} \\left(\\beta \\left(\\frac{x}{\\mu}\\right)^{\\gamma} + 1\\right) & \\text{for}\\: \\gamma > -1 \\vee \\gamma < -1 \\\\\\frac{t_{0} \\left(\\beta \\mu + x\\right)}{x} & \\text{otherwise} \\end{cases}$"
          },
          "metadata": {}
        }
      ],
      "source": [
        "# The original link performance function, tij, can be reproduced by differentiating Tij.\n",
        "t_repro = sympy.simplify(sympy.diff(T,x))\n",
        "#sympy.simplify(sympy.diff(t0*x*(1+beta/(1+gamma)*(x/mu)**gamma), x))\n",
        "print(\"T:\")\n",
        "display(T)\n",
        "print(\"t (reproduced by differentiating T):\")\n",
        "display(t_repro)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1KYLagRRagMS"
      },
      "source": [
        "`TNTP` クラスには，この積分されたリンク性能関数およびそれを用いた等価最適化問題の目的関数値を評価する関数を用意している:\n",
        "- `T(x)` : リンク数次元のnp.array型ベクトル$x$ を引数として，同次元の積分されたリンク費用を返す\n",
        "- `Z(x)` : 等価最適化問題の目的関数値を返す"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MZFfhQq7agMS"
      },
      "source": [
        "## Shortest Path Search\n",
        "Frank-Wolfe法の補助問題の求解で必要となる最短経路探索を解くための Dijkstra法は `scipy.sparse.csgraph.dijkstra` で実装されている．\n",
        "これを呼び出すためには，一度，ノード間の距離行列を，`scipy.sparse.csr_matrix`型の疎行列として作成する必要がある．\n",
        "`scipy.sparse.csr_matrix` は，各リンクの所要時間 `cost` とリンク・インデックス集合 `ntw.links` を用いた以下のコマンドで定義できる:\n",
        "```\n",
        "w = scipy.sparse.csr_matrix((cost, zip(*ntw.links)))\n",
        "```\n",
        "ここで，`zip(*ntw.links)` は「発着ノードペアのリスト」を「発ノードリストと着ノードリストのペア」に置き換えるコマンド．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {
        "id": "SuNPFND5agMS"
      },
      "outputs": [],
      "source": [
        "# Create the weight matrix by using the free flow travel time as the link cost\n",
        "w = sparse.csr_matrix((ntw.fftt, zip(*ntw.links)))"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "UjKpDjDUagMS",
        "outputId": "da72ed0f-6711-4fac-d8b4-d0d1f08ff91d"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "[[0.0, 6.0, 4.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, ...],\n",
            " [6.0, 0.0, 0.0, 0.0, 0.0, 5.0, 0.0, 0.0, 0.0, 0.0, ...],\n",
            " [4.0, 0.0, 0.0, 4.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, ...],\n",
            " [0.0, 0.0, 4.0, 0.0, 2.0, 0.0, 0.0, 0.0, 0.0, 0.0, ...],\n",
            " [0.0, 0.0, 0.0, 2.0, 0.0, 4.0, 0.0, 0.0, 5.0, 0.0, ...],\n",
            " [0.0, 5.0, 0.0, 0.0, 4.0, 0.0, 0.0, 2.0, 0.0, 0.0, ...],\n",
            " [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 3.0, 0.0, 0.0, ...],\n",
            " [0.0, 0.0, 0.0, 0.0, 0.0, 2.0, 3.0, 0.0, 10.0, 0.0, ...],\n",
            " [0.0, 0.0, 0.0, 0.0, 5.0, 0.0, 0.0, 10.0, 0.0, 3.0, ...],\n",
            " [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 3.0, 0.0, ...],\n",
            " ...]\n"
          ]
        }
      ],
      "source": [
        "# 疎行列として定義された重み行列を標準の行列として表示させる\n",
        "pprint(w.toarray().tolist(), max_seq_length=10)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "rSculFZhagMS"
      },
      "source": [
        "こうして用意された重み行列 `w` を用いれば，`scipy.sparse.csgraph.dijkstra` によって任意の起点から各ノードへの最短経路を計算できる．具体的には，ノード・インデックス `orig` から各ノードへの最短経路を得るコードは以下のように表せる:\n",
        "```\n",
        "pi, pred = scipy.sparse.csgraph.dijkstra(w,indices=orig,return_predecessors=True)\n",
        "```\n",
        "戻り値は，それぞれ，\n",
        "- `pi`: 起点から各ノードへの最短経路費用\n",
        "- `pred` : 各ノードの最短経路上の先行ポインタ(predecessor)．起点ノードなど，先行ポインタが無ければ`-9999`.\n",
        "\n",
        "である．ここで，それぞれのオプションは，下記の意味を持つ:\n",
        "\n",
        "- `indices`: 最短経路の起点インデックス．リストとして複数与えることも可能. 省略すると，全てのノードを起点とする最短経路を探索．\n",
        "- `return_predecessors`: `True` を与えると `pred` を戻り値で返す. デフォルトは `False`.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "S4Zd2BCIagMS",
        "outputId": "ed9dd9cc-8279-43a0-f584-ba1c56fdcf29"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "pi:\n",
            "[0.0, 6.0, 4.0, 8.0, 10.0, 11.0, 16.0, 13.0, 15.0, 18.0, ...]\n",
            "pred:\n",
            "[-9999, 0, 0, 2, 3, 1, 7, 5, 4, 8, ...]\n"
          ]
        }
      ],
      "source": [
        "orig_bn = 1\n",
        "orig = ntw.nid_of[orig_bn]\n",
        "pi,pred = sparse.csgraph.dijkstra(w,indices=orig,return_predecessors=True)\n",
        "\n",
        "#\n",
        "print(\"pi:\")\n",
        "pprint(pi.tolist(),max_seq_length=10)\n",
        "print(\"pred:\")\n",
        "pprint(pred.tolist(), max_seq_length=10)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "sN1WZEQiagMS"
      },
      "source": [
        "## All-or-Nothing Assignment as The Solution of Auxiliary Problem\n",
        "Frank-Wolfe法の補助問題\\[AP\\]の解は，最短経路に全ての交通需要を載せる AoN (*All-or-Nothing*)配分に等しい．\n",
        "AoN配分の単純な計算方法として「各起終点ペアごとに最短経路上のリンクに交通需要に等しい交通量を載せたものを，全ての起終点について足し合わせる」こともできるが，Dijkstra法によって，それぞれの起点から全てのノードへの最短経路が，起点を根とするツリー構造によって与えられることを利用すれば，より効率的に AoN 配分を計算できる．\n",
        "\n",
        "具体的な方法は執筆中．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "id": "OIyasT1SagMT"
      },
      "outputs": [],
      "source": [
        "# use the free flow travel time as the link cost\n",
        "w = sparse.csr_matrix((ntw.fftt, zip(*ntw.links)))\n",
        "\n",
        "orig_bn = 1\n",
        "orig = ntw.nid_of[orig_bn]\n",
        "pi,pred = sparse.csgraph.dijkstra(w,indices=orig,return_predecessors=True)\n",
        "\n",
        "x = np.zeros(ntw.num_links) # Link flow of All-or-Nothing assignment\n",
        "X = np.zeros(ntw.num_nodes) # Total traffic for each node to the corresponding subtree on the shortest path\n",
        "for j, pi_j in sorted(enumerate(pi),key=itemgetter(1,0), reverse=True): # sort the destinations by the shortest path in reverse order\n",
        "    j_bn = ntw.nodes_bn[j] # \n",
        "    i = pred[j] # predecessor of node j\n",
        "    if i == -9999: # if node j does not have predecessor (i.e. there is no path from origin to node j)\n",
        "        if j == orig: continue\n",
        "        if j is not orig and j_bn in ntw.trips[orig_bn] and ntw.trips[orig_bn][j_bn] > 0:\n",
        "            print(\"trip demand for O-D pair(%d,%d) can not be assigned\"%(orig_bn,j_bn))\n",
        "        continue\n",
        "    lid = ntw.lid_of[i,j]\n",
        "    x[lid] += X[j]\n",
        "    if j_bn in ntw.trips[orig_bn]:\n",
        "        x[lid] += ntw.trips[orig_bn][j_bn]\n",
        "    X[i] += x[lid]"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "vJ4A40NCagMT",
        "outputId": "2e75d4ba-fa6e-479a-d574-942a4f98e768"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "pi:\n",
            "[0.0, 6.0, 4.0, 8.0, 10.0, 11.0, 16.0, 13.0, 15.0, 18.0, ...]\n",
            "pred:\n",
            "[-9999, 0, 0, 2, 3, 1, 7, 5, 4, 8, ...]\n",
            "x:\n",
            "{(0, 1): 3300.0,\n",
            " (0, 2): 5500.0,\n",
            " (1, 0): 0.0,\n",
            " (1, 5): 3200.0,\n",
            " (2, 0): 0.0,\n",
            " (2, 3): 2500.0,\n",
            " (2, 11): 2900.0,\n",
            " (3, 2): 0.0,\n",
            " (3, 4): 2000.0,\n",
            " (3, 10): 0.0,\n",
            " ...}\n"
          ]
        }
      ],
      "source": [
        "# 起点から各ノードまでの最短経路費用，先行ポインタおよびリンク交通量を表示\n",
        "print(\"pi:\")\n",
        "pprint(pi.tolist(), max_seq_length=10)\n",
        "print(\"pred:\")\n",
        "pprint(pred.tolist(), max_seq_length=10)\n",
        "print(\"x:\")\n",
        "pprint({(ntw.nodes[i],ntw.nodes[j]):x[lid] for lid, (i,j) in enumerate(ntw.links)}, max_seq_length=10)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "P5IpAx96agMT"
      },
      "source": [
        "同様の処理と，その処理を各起点に対して行う関数を `TNTP` クラスのメンバ関数として用意してある:\n",
        "- `AoN_O2M(w, orig_bn)` : 重み行列`w` を与件とし，起点 `orig_bn` から他のノードへの all-or-nothign 配分を行なった結果(リンク次元の `np.array`)を返す\n",
        "- `AoN(w)` : 重み行列 `w` を与件とし，全ての起点について行なった all-or-nothing 配分を重ね合わせた結果(リンク次元の `np.array`)を返す\n",
        "- `AoN_init()` : リンク費用を自由走行時間として全起点について all-or-nothing 配分を行なった結果(リンク次元の `np.array`)を返す"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CuQ_pEpnagMT"
      },
      "source": [
        "全ての起点についての all-or-nothing 配分にどの程度時間がかかるのか測ってみよう．セルの先頭に `%%time` という `magic funciton` を記述すると，当該セルの実行時間を計測してくれる．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "XDRfwJ4-agMT",
        "outputId": "a9dd7c72-9eeb-4564-9279-31b43aa53d00"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "CPU times: user 21.9 ms, sys: 3.98 ms, total: 25.9 ms\n",
            "Wall time: 30.1 ms\n"
          ]
        }
      ],
      "source": [
        "%%time \n",
        "# Evaluate the execution time of the current cell by using %%time\n",
        "w0 = sparse.csr_matrix((ntw.fftt, zip(*ntw.links))) # Use the free flow travel time as the link cost\n",
        "x0 = ntw.AoN(w0) # initial "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TLrRNX2RagMT"
      },
      "source": [
        "## Determine the Step-Size and Update the Tentative Solution\n",
        "補助問題\\[AP\\]の解(補助解)として得られた all-or-nothing 配分$\\mathbf{y}$から，解の改訂方向が求められる．この改訂方向に「どれだけ進むか(ステップ・サイズ)」を求めよう．\n",
        "\n",
        "いま，自由走行時間をリンク費用と見なして all-or-nothing 配分したものを初期暫定解$\\mathbf{x}^{(0)}$とし，繰返しカウンターを$n:=0$とする．\n",
        "いま，暫定解$\\mathbf{x}^{(n)}$を与件として補助問題を解いたもの(i.e. リンク費用を$\\mathbf{t}(\\mathbf{x}^{(n)})$ として all-or-nothing配分したもの)を$\\mathbf{y}^{(n)}$とし，改訂方向を$\\mathbf{d}^{(n)} := \\mathbf{y}^{(n)} - \\mathbf{x}^{(n)}$ としよう．ステップ・サイズを$\\alpha \\in [0,1]$とし，\n",
        "$$\n",
        "\\begin{align}\n",
        "g^{(n)}(\\alpha) &:= Z\\left(\\mathbf{x}^{(n)} + \\alpha \\mathbf{d}^{(n)}\\right)\\\\\n",
        "&= \n",
        "Z\\left((1-\\alpha)\\mathbf{x}^{(n)} + \\alpha \\mathbf{y}^{(n)}\\right)\n",
        "\\end{align}\n",
        "$$\n",
        "とする．Frank-Wolfe法では，これが最小となるような最適なステップ・サイズ$\\alpha^{(n)}$を求め，暫定解を\n",
        "$$\n",
        "\\mathbf{x}^{(n+1)} := \\mathbf{x}^{(n)} + \\alpha \\mathbf{d}^{(n)}\n",
        "$$\n",
        "と改訂する．\n",
        "\n",
        "初期解$\\mathbf{x}^{(0)}$と，それに対応する補助問題の解$\\mathbf{y}^{(0)}$ を与件とした時，$g(\\alpha)$をプロットしてみよう．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {
        "id": "K86OcLVLagMT"
      },
      "outputs": [],
      "source": [
        "from matplotlib import pyplot as plt"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 463
        },
        "id": "zKcjXAeNagMT",
        "outputId": "c24fa33b-aaef-45e0-a0f5-2292a9414a02"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "[<matplotlib.lines.Line2D at 0x7ffb1c880df0>]"
            ]
          },
          "metadata": {},
          "execution_count": 12
        },
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 640x480 with 1 Axes>"
            ],
            "image/png": "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3vrOY9avX68xY8bI4XCoX79+evHFF9s3pOHDVqxYYdjtduOFF14wvv76a+O2224zIiMjjYKCgjPu/9lnnxk2m8147LHHjF27dhn33nuvERgYaOzcubODk3sXT8/zTTfdZCxdutTYtm2bsXv3buOWW24xIiIijLy8vA5O7n08PddNDh06ZHTv3t2YPHmycc0113RMWC/m6Xmuq6szxo4da1x55ZXGhg0bjEOHDhnr1683MjMzOzi5d/H0PP/zn/80HA6H8c9//tM4dOiQsW7dOiMhIcGYP39+Byf3LmvWrDHuuece44033jAkGW+++eY598/KyjKCg4ONBQsWGLt27TKefvppw2azGWvXrm23jD5dRsaNG2fMmzev+d9dLpeRmJhoLF68+Iz733DDDca0adNO2TZ+/Hjjpz/9abvm9Haenudva2hoMMLCwoyXXnqpvSL6jNac64aGBmPixInGX//6V2POnDmUkRbw9Dz/+c9/Nvr06WM4nc6OiugTPD3P8+bNMy655JJTti1YsMCYNGlSu+b0JS0pI7/97W+NoUOHnrJt5syZxtSpU9stl88O0zidTmVkZCgtLa15m9VqVVpamjZu3HjGYzZu3HjK/pI0derUs+6P1p3nb6uurlZ9fb2ioqLaK6ZPaO25fvDBBxUbG6sf//jHHRHT67XmPL/99ttKTU3VvHnzFBcXp2HDhumRRx6Ry+XqqNhepzXneeLEicrIyGgeysnKytKaNWt05ZVXdkhmf2HGe6FXPCivNYqLi+VyuRQXF3fK9ri4OO3Zs+eMx+Tn559x//z8/HbL6e1ac56/7c4771RiYuJpv/w4VWvO9YYNG/T8888rMzOzAxL6htac56ysLH344Ye6+eabtWbNGh04cEA///nPVV9fr0WLFnVEbK/TmvN80003qbi4WBdeeKEMw1BDQ4Nuv/123X333R0R2W+c7b2wvLxcNTU16tKlS5t/TZ+9MgLvsGTJEq1YsUJvvvmmgoKCzI7jUyoqKjRr1iwtX75c0dHRZsfxaW63W7GxsXruueeUkpKimTNn6p577tGyZcvMjuZT1q9fr0ceeUTPPvustm7dqjfeeEOrV6/WQw89ZHY0nCefvTISHR0tm82mgoKCU7YXFBQoPj7+jMfEx8d7tD9ad56bPP7441qyZIk++OADjRgxoj1j+gRPz/XBgweVnZ2t6dOnN29zu92SpICAAO3du1d9+/Zt39BeqDW/0wkJCQoMDJTNZmveNnjwYOXn58vpdMput7drZm/UmvN83333adasWbr11lslScOHD1dVVZV+8pOf6J577pHVyt+v28LZ3gvDw8Pb5aqI5MNXRux2u1JSUpSent68ze12Kz09XampqWc8JjU19ZT9Jen9998/6/5o3XmWpMcee0wPPfSQ1q5dq7Fjx3ZEVK/n6bkeNGiQdu7cqczMzObX1VdfrSlTpigzM1NJSUkdGd9rtOZ3etKkSTpw4EBz2ZOkffv2KSEhgSJyFq05z9XV1acVjqYCaPCYtTZjynthu02N7QRWrFhhOBwO48UXXzR27dpl/OQnPzEiIyON/Px8wzAMY9asWcZdd93VvP9nn31mBAQEGI8//rixe/duY9GiRdza2wKenuclS5YYdrvdWLVqlXHs2LHmV0VFhVnfgtfw9Fx/G3fTtIyn5zknJ8cICwsz7rjjDmPv3r3Gf/7zHyM2NtZ4+OGHzfoWvIKn53nRokVGWFiY8a9//cvIysoy3nvvPaNv377GDTfcYNa34BUqKiqMbdu2Gdu2bTMkGU8++aSxbds24/Dhw4ZhGMZdd91lzJo1q3n/plt7f/Ob3xi7d+82li5dyq295+vpp582evbsadjtdmPcuHHGF1980fyxiy66yJgzZ84p+7/66qvGgAEDDLvdbgwdOtRYvXp1Byf2Tp6c5169ehmSTnstWrSo44N7IU9/p7+JMtJynp7nzz//3Bg/frzhcDiMPn36GL///e+NhoaGDk7tfTw5z/X19cbvfvc7o2/fvkZQUJCRlJRk/PznPzdOnDjR8cG9yEcffXTG/+c2nds5c+YYF1100WnHjBo1yrDb7UafPn2Mv/3tb+2a0WIYXNsCAADm8dk5IwAAwDtQRgAAgKkoIwAAwFSUEQAAYCrKCAAAMBVlBAAAmIoyAgAATEUZAQAApqKMAAAAU1FGAACAqSgjAADAVJQRAABgqv8fP0oI7dIAjPcAAAAASUVORK5CYII=\n"
          },
          "metadata": {}
        }
      ],
      "source": [
        "x0 = ntw.AoN(ntw.t_mat()) # AoN assignment only based on the free flow travel time\n",
        "y0 = ntw.AoN(ntw.t_mat(x0))\n",
        "Dalpha = 0.01\n",
        "alpha_set = np.arange(0, 1+Dalpha, Dalpha)\n",
        "plt.plot(alpha_set, [ntw.Z((1-alpha)*x0+alpha*y0) for alpha in alpha_set])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ThL9DM-PagMT"
      },
      "source": [
        "黄金分割法(golden section method)などによる一次元関数の最適化は `scipy.optimize.minimize_scalar` 関数によって実装されている．`lambda` を用いた無名関数(anonymous function)を用いれば，最適なαを求めるためのコードは以下のように記述できる．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 13,
      "metadata": {
        "id": "CYQkIo85agMT"
      },
      "outputs": [],
      "source": [
        "from scipy import optimize\n",
        "g = lambda alpha: ntw.Z((1-alpha)*x0+alpha*y0)\n",
        "res = optimize.minimize_scalar(g, bounds=[0,1])\n",
        "alpha = res.x"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "FiHhtJ3YagMT"
      },
      "source": [
        "同等の関数は `TNTP` にも実装されている:\n",
        "- `FindAlpha(x,y)`: 暫定解`x`, 補助解`y` として最適なステップ・サイズを返す\n",
        "\n",
        "$\\mathbf{x}^{(n+1)} := \\mathbf{x}^{(n)} + \\alpha (\\mathbf{y}^{(n)} - \\mathbf{x}^{(n)})$ と暫定解を改訂しながら，正しく $g(\\alpha)$を最小化させるステップ・サイズが求められていることを確認しよう．まず，下記のコマンドで初期解(自由走行時間のみをリンク費用と見なしてall-or-nothing配分したもの)を`x`に格納しておく．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 14,
      "metadata": {
        "id": "k31_QLv9agMT"
      },
      "outputs": [],
      "source": [
        "x = ntw.AoN_init()  # give x0 as the first tentative solution"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "cCzi307OagMT"
      },
      "source": [
        "以下のセルを評価するたびに暫定解が改訂されていく．`Z=`の値が小さくなっていること，`alpha`が常に目的関数が最小となる点に一致するように求められることを確認しよう．"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 15,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 463
        },
        "id": "XlZYhvFwagMT",
        "outputId": "f3a586e7-9ecd-4618-85b5-f3ebf93f8af4"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Z=6879302.05\n"
          ]
        },
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 640x480 with 1 Axes>"
            ],
            "image/png": "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\n"
          },
          "metadata": {}
        }
      ],
      "source": [
        "# evaluating this cell updates the tentative solution\n",
        "y = ntw.AoN(ntw.t_mat(x))\n",
        "alpha = ntw.FindAlpha(x,y)\n",
        "alpha_set = np.arange(0, 1+Dalpha, Dalpha)\n",
        "plt.plot(alpha_set, [ntw.Z((1-alpha)*x+alpha*y) for alpha in alpha_set])\n",
        "plt.axvline(x = alpha, color='black', linestyle='dashed', linewidth=1)\n",
        "x += alpha*(y-x)\n",
        "print(\"Z=%8.2f\"%ntw.Z(x))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "coDLUJimagMT"
      },
      "source": [
        "## Convergence Test\n",
        "上述の解の改訂を繰返すほど目的関数は徐々に小さくなっていく(i.e. リンク・フローが均衡解に漸近する)．一般的には，適当な条件を満足した時点で終了させる．ここでは，以下の3つの収束条件について，いずれかが満足された時点で終了することとしよう．\n",
        "1. $n$回目繰返しにおける目的関数を$Z^{(n)}$とするとき，$\\frac{Z^{(n-1)}-Z^{(n)}}{Z^{(n-1)}} \\leq \\epsilon_{Z}$\n",
        "2. $n$回目繰返しにおけるリンク・フローを$x_{ij}^{(n)}$とするとき, $\\frac{\\sqrt{\n",
        "\\sum_{ij} \\left( x_{ij}^{(n)} - x_{ij}^{(n-1)}\\right)^{2}\n",
        "}}{\\sum_{ij} x_{ij}^{(n-1)}} \\leq \\epsilon_{x}$ \n",
        "3. $n$回目繰返しにおける，起点$r$からノード$i(\\ne r)$への最小交通費用を$\\pi_{i}^{r(n)}$ と記述する時,\n",
        "  $\n",
        "  \\sum_{ri \\in \\mathbb{W}}\n",
        "  \\frac{\\left|\n",
        "  \\pi_{i}^{r(n)} - \\pi_{i}^{r(n-1)}\n",
        "  \\right|\n",
        "  }\n",
        "  {\\pi_{i}^{r(n-1)}} \\leq \\epsilon_{\\pi}$"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 16,
      "metadata": {
        "id": "uCzA1Se9agMZ"
      },
      "outputs": [],
      "source": [
        "# Parameters for convergence test\n",
        "max_itr = 500 # the upper limit of iteration\n",
        "TOL_Z_rate = 1e-6 # epsilon_Z\n",
        "TOL_x_rate = 1e-5 # epsilon_x\n",
        "TOL_pi_rate = 1e-5 # epsilon_pi\n",
        "\n",
        "# Lists for log\n",
        "Z = list() # objective function at each iteration\n",
        "Z_rate = list() # change rate in the objective function\n",
        "x_rate = list() # change rate in the link flow\n",
        "pi_rate = list() # change rate in the shortest travel time\n",
        "\n",
        "# initialize\n",
        "t0 = ntw.t_mat()\n",
        "x0 = ntw.AoN(t0)\n",
        "pi0 = ntw.ShortestTravelTime(t0)\n",
        "Z.append(ntw.Z(x0))\n",
        "\n",
        "# main loop\n",
        "for itr in range(max_itr):\n",
        "    # Obtain the auxliary solution as the all-or-nothing assignment\n",
        "    y = ntw.AoN(ntw.t_mat(x0))\n",
        "    # Find the best step size\n",
        "    alpha = ntw.FindAlpha(x0,y)\n",
        "    # Update the tentative solution\n",
        "    x = x0 + alpha*(y-x0)\n",
        "    pi = ntw.ShortestTravelTime(ntw.t_mat(x))\n",
        "    # Calculate change rates and update logs\n",
        "    Z.append(ntw.Z(x))\n",
        "    Z_rate.append((-Z[-1]+Z[-2])/Z[-2])\n",
        "    pi_rate.append(sum(abs(pi[pi0>0]-pi0[pi0>0])/pi0[pi0>0]))\n",
        "    x_rate.append(np.sqrt(np.sum((x0-x)**2))/(np.sum(x0)))\n",
        "    # Convergence check\n",
        "    if Z_rate[-1] < TOL_Z_rate or x_rate[-1] < TOL_x_rate or pi_rate[-1] < TOL_pi_rate:\n",
        "        break\n",
        "    # Memorize the current solution\n",
        "    x0 = x.copy()\n",
        "    pi0 = pi.copy()\n",
        "    Z0 = Z"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 17,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 445
        },
        "id": "Ee0QYDNqagMZ",
        "outputId": "abcd161b-2e5f-413c-9450-4afdfa83581b"
      },
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 640x480 with 2 Axes>"
            ],
            "image/png": "iVBORw0KGgoAAAANSUhEUgAAAigAAAGsCAYAAAD3xFzWAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/bCgiHAAAACXBIWXMAAA9hAAAPYQGoP6dpAAB6F0lEQVR4nO3deVxU9frA8c/MwLAvIruCqKFlKu5maWFhZv4srcx2s7JbaWlcu2mWZnW11au3LMsyq1tpWdqiaYV7ouaCmrmL4sKqsu8z5/fHyMDAsAwCMxye9+s1L+Z8z/ec88wUx4fvdjSKoigIIYQQQjgQrb0DEEIIIYSoTBIUIYQQQjgcSVCEEEII4XAkQRFCCCGEw5EERQghhBAORxIUIYQQQjgcSVCEEEII4XAkQRFCCCGEw5EERQghhBAORxIUIYQQQjicZpWgbNq0iREjRhAaGopGo2HlypU2Hf/yyy+j0WiqvDw8PBonYCGEEELUS7NKUPLy8oiKimLBggX1On7KlCkkJydbvLp06cLo0aMbOFIhhBBCXI5mlaAMGzaM1157jVGjRlndX1RUxJQpU2jTpg0eHh7079+fDRs2mPd7enoSHBxsfqWmpvL333/z6KOPNtEnEEIIIURdNKsEpTYTJ04kPj6epUuXsm/fPkaPHs0tt9zC0aNHrdb/+OOP6dSpE4MGDWriSIUQQghRE9UkKElJSXz66ad8++23DBo0iI4dOzJlyhQGDhzIp59+WqV+YWEhX375pbSeCCGEEA7Iyd4BNJT9+/djMBjo1KmTRXlRURGtW7euUn/FihXk5OQwduzYpgpRCCGEEHWkmgQlNzcXnU7Hrl270Ol0Fvs8PT2r1P/444/5v//7P4KCgpoqRCGEEELUkWoSlJ49e2IwGEhLS6t1TEliYiLr16/nxx9/bKLohBBCCGGLZpWg5ObmcuzYMfN2YmIiCQkJ+Pn50alTJ+6//34eeugh3nnnHXr27El6ejpxcXF0796d4cOHm49bvHgxISEhDBs2zB4fQwghhBC10CiKotg7iLrasGEDgwcPrlI+duxYlixZQklJCa+99hqff/45Z8+exd/fn2uuuYZZs2bRrVs3AIxGI+3ateOhhx7i3//+d1N/BCGEEELUQbNKUIQQQgjRMqhmmrEQQggh1EMSFCGEEEI4nGYxSNZoNHLu3Dm8vLzQaDT2DkeIFkdRFHJycggNDUWrbR5/18h9Qwj7u5x7R7NIUM6dO0dYWJi9wxCixTt9+jRt27a1dxh1IvcNIRxHfe4dzSJB8fLyAkwf0Nvb287RCNHyZGdnExYWZv5dbA7kviGE/V3OvaNZJChlzbPe3t5yoxHCjppTV4ncN4RwHPW5dzSPzmQhhBBCtCiSoAghhBDC4UiCIoQQQgiH0yzGoAhhb4qiUFpaisFgsHcojcbZ2bnKk8CFaM4MBgMlJSX2DkPVdDodTk5OjTI+TRIUIWpRXFxMcnIy+fn59g6lUWk0Gtq2bYunp6e9QxHisuXm5nLmzBnkaS6Nz93dnZCQEPR6fYOeVxIUIWpgNBpJTExEp9MRGhqKXq9vVjNZ6kpRFNLT0zlz5gyRkZHSkiKaNYPBwJkzZ3B3dycgIECVv7OOQFEUiouLSU9PJzExkcjIyAZdyFESFCFqUFxcjNFoJCwsDHd3d3uH06gCAgI4efIkJSUlDpOgZGZmEhMTQ2lpKaWlpUyaNInx48fbOyzh4EpKSlAUhYCAANzc3Owdjqq5ubnh7OzMqVOnKC4uxtXVtcHOLQmKEHXQXJZ3vxyO+Feml5cXmzZtwt3dnby8PLp27codd9xB69at7R2aaAYc8f9pNWqs+6P677pCiGZLp9OZW66KiopQFEXGFAjRQticoGzatIkRI0YQGhqKRqNh5cqVtR5TVFTE9OnTadeuHS4uLkRERLB48eL6xCuEaEbqcr9YsGABERERuLq60r9/f3bs2GGxPzMzk6ioKNq2bctzzz2Hv79/E0UvhLAnmxOUvLw8oqKiWLBgQZ2Pufvuu4mLi+OTTz7h8OHDfP3113Tu3NnWSwshmpna7hfLli0jNjaWmTNnsnv3bqKiohg6dChpaWnmOr6+vuzdu5fExES++uorUlNTmyp8IYQd2ZygDBs2jNdee41Ro0bVqf6aNWvYuHEjq1evJiYmhoiICAYMGMB1111nc7BCiLrZsGEDGo2m2tfgwYObJI7a7hdz585l/PjxjBs3ji5durBw4ULc3d2ttrAGBQURFRXF5s2brZ6rqKiI7Oxsi5cQzYU9fmdffvllevTo0eDnbSiNPgblxx9/pE+fPrz55pu0adOGTp06MWXKFAoKCqo9pr43mjmrD/Lyjwe4kFfcUOEL0Sxde+21JCcnV3l9+OGHaDQannrqKXuHSHFxMbt27SImJsZcptVqiYmJIT4+HoDU1FRycnIAyMrKYtOmTdW2vs6ZMwcfHx/zKywsrE5x5O/eTcq/Z5O5fPllfiIh6q8hf2eLi9Xxb2CjJygnTpxgy5Yt/PXXX6xYsYJ58+axfPnyGr/s+t5o/rftFEu2niSnUFYOFI1DURTyi0vt8rJlcKheryc4ONjidfHiRaZMmcILL7zA6NGjG/FbqpuMjAwMBgNBQUEW5UFBQaSkpABw6tQpBg0aRFRUFIMGDeLpp5+mW7duVs83bdo0srKyzK/Tp0/XKY6iI0e5+MUX5GzYcFmfRzgwRYHiPPu86vh7ezm/sxEREbz66qs89NBDeHt78/jjjwPw/PPP06lTJ9zd3enQoQMvvfSSeWXdJUuWMGvWLPbu3WtupVmyZAlgGvf12GOPERAQgLe3NzfeeCN79+69vP8G9dDo04yNRiMajYYvv/wSHx8fwNSse9ddd/H+++9bnaM+bdo0YmNjzdvZ2dl1SlJkSplobAUlBrrMWGuXa//9ylDc9fX7lc3MzOT2228nOjqaV199tYEjazz9+vUjISGhTnVdXFxwcXGx+Roa50vfaUmpzceKZqIkH2aH2ufaL5wDvYfNh9n6O/v2228zY8YMZs6caS7z8vJiyZIlhIaGsn//fsaPH4+Xlxf/+te/GDNmDH/99Rdr1qzh999/BzD/Gz169Gjc3Nz45Zdf8PHx4cMPP+Smm27iyJEj+Pn52fxZ6qvRE5SQkBDatGlj/uAAV111FYqimFetrKy+N5oyMgtRiHJGo5H77rsPJycnvvzyS4dJ5P39/dHpdFUGvaamphIcHNxkcWicnQFQ5JktwkHU53f2xhtv5J///KdF2Ysvvmh+HxERwZQpU1i6dCn/+te/cHNzw9PTEycnJ4vfty1btrBjxw7S0tLM/w6//fbbrFy5kuXLl5tbZ5pCoyco1113Hd9++y25ubnmZ3wcOXIErVZL27ZtG/RaZf8JJT8RjcXNWcffrwy127Xr44UXXiA+Pp4dO3bg5eXVwFHVn16vp3fv3sTFxTFy5EjAdGOOi4tj4sSJTRaHxsl0G1RKpQVFtZzdTS0Z9rq2jerzO9unT58qZcuWLeO///0vx48fJzc3l9LSUry9vWs8z969e8nNza2yGGJBQQHHjx+v+4doADYnKLm5uRw7dsy8nZiYSEJCAn5+foSHhzNt2jTOnj3L559/DsB9993Hq6++yrhx45g1axYZGRk899xzPPLIIw2/BLFj/GEoVEyj0dS7m8Ueli5dyttvv82qVaustlY2ttruF7GxsYwdO5Y+ffrQr18/5s2bR15eHuPGjWu6IKUFRf00mnp1s9hDfX9nPTwsP198fDz3338/s2bNYujQofj4+LB06VLeeeedGs+Tm5tLSEgIG6yMyfL19a1zPA3B5jvtzp07LaY7lY0VGTt2LEuWLCE5OZmkpCTzfk9PT3777Teefvpp+vTpQ+vWrbn77rt57bXXGiB862SlSSEgISGBRx99lNdff52hQ+3T6lPb/WLMmDGkp6czY8YMUlJS6NGjB2vWrKkycLYxSQuKcBQN+Tu7detW2rVrx/Tp081lp06dsqij1+sxGAwWZb169SIlJQUnJyciIiIuK4bLZXOCEh0dXWMCUDYKuKIrr7yS3377zdZL2Uy6eIQwycjIYOTIkURHR/PAAw+YZ8WU0el0BAQENHoctd0vACZOnNikXTqVaZxNj4iXFhRhTw39OxsZGUlSUhJLly6lb9++rFq1ihUrVljUiYiIMLdqtm3bFi8vL2JiYhgwYAAjR47kzTffpFOnTpw7d45Vq1YxatQoq11JjaX5tFXXgaMM/hPC3latWsWpU6c4deoUISEhVfa3a9eOkydPNn1gDqi8BUUSFGE/Df07e9ttt/Hss88yceJEioqKGD58OC+99BIvv/yyuc6dd97J999/z+DBg8nMzOTTTz/l4YcfZvXq1UyfPp1x48aRnp5OcHAw119/fZO2bAJolGbQH5KdnY2Pjw9ZWVk1DvCJmvUrWQUl/B57A1cEejZhhEKtCgsLSUxMpH379g36GHFHVNNnrevvoCOpa8z5u3dz6r77cW4XzhVr7TOFXDSslvR76wga696hqqcZlzegOHzOJYRwEGUtKLIOihCORV0Jir0DEEI0O7IOihCOSVUJShnH77QSQjgKmcUjhGNSVYJSNkhW8hMhRF1JC4oQjkldCYq9AxCq1QzGkl+2lvAZrXK6lKBIC4oQDkVVCUqZlnqfFQ3P+dJf1/n5+XaOpPGVPaJdp6vfkvrNlbkFRRIUIRyKytZBMf1UpJNHNBCdToevry9paWkAuLu7q3K9HaPRSHp6Ou7u7jg5qeq2UCvz04xLS1EURZX/fYVojlR2J5Ibi2h4ZU/6LEtS1Eqr1RIeHt7i/oHWVEzISkpAr7dfMEIIM5UlKCbSxSMakkajISQkhMDAQEpUPJBSr9ej1aqy17dGZV08YBooq5EERQiHoKoExdzFIwmKaAQ6na7Fjc9oCSq2oMg4FCEch6r+XGpZDdNCiAZRMUFRcQuZEBVFR0czefJke4dRI1UlKGVkkKwQoq40Gg3ITB6hEmrqhlZVgiJdPEKI+pDF2tRNURTyS/Lt8qrr+kJlTw2ePXu2uWzr1q3o9Xri4uKsHnPy5Ek0Gg3Lli3jhhtuwNXVlS+//JLz589z77330qZNG9zd3enWrRtff/21+biHH36YjRs3Mn/+fDQaDRqNxvyk5L/++othw4bh6elJUFAQDz74IBkZGfX/8i+DusagSCePEKIeNE5OKIAiDwxUpYLSAvp/1d8u195+33bcnd1rrRcQEMDixYsZOXIkN998M507d+bBBx9k4sSJ3HTTTTUeO3XqVN555x169uyJq6srhYWF9O7dm+effx5vb29WrVrFgw8+SMeOHenXrx/z58/nyJEjdO3alVdeecV8/czMTG688UYee+wx/vOf/1BQUMDzzz/P3Xffzbp16xrk+7CFqhIUIYSoD2lBEY7g1ltvZfz48dx///306dMHDw8P5syZU+txkydP5o477rAomzJlivn9008/zdq1a/nmm2/o168fPj4+6PV63N3dzcsoALz33nv07NnTohVn8eLFhIWFceTIETp16tQAn7LuVJWgSBePEKI+yh8YKAmKGrk5ubH9vu12u7Yt3n77bbp27cq3337Lrl27cHFxqfWYPn36WGwbDAZmz57NN998w9mzZykuLqaoqAh395pbcvbu3cv69evx9PSssu/48eOSoFwO6eARQtSHeS0UaUFRJY1GU6duFkdw/Phxzp07h9Fo5OTJk3Tr1q3WYzw8PCy233rrLebPn8+8efPo1q0bHh4eTJ482fw4i+rk5uYyYsQI3njjjSr7QkJCbPsgDUBVCUoZmcUjhLBFeQuKjEER9lNcXMwDDzzAmDFj6Ny5M4899hj79+8nMDDQpvP88ccf3H777TzwwAOA6VEWR44coUuXLuY6er0eg8FgcVyvXr347rvviIiIcIhHXqhsFo+pDUW6eIQQtpAxKMIRTJ8+naysLP773//y/PPP06lTJx555BGbzxMZGclvv/3G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\n"
          },
          "metadata": {}
        }
      ],
      "source": [
        "# Plot the convergence of Z, Z_rate, x_rate, pi_rate\n",
        "plt.subplot(1,2,1)\n",
        "plt.plot(Z,'C0', label=\"Z\")\n",
        "plt.legend()\n",
        "plt.yscale('linear')\n",
        "plt.subplot(1,2,2)\n",
        "plt.plot(Z_rate, 'C1',label=\"Z rate\")\n",
        "plt.plot(x_rate, 'C2', label=\"x rate\")\n",
        "plt.plot(pi_rate, 'C3', label=\"$\\pi$ rate\")\n",
        "plt.legend()\n",
        "plt.yscale('log')"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 18,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 448
        },
        "id": "iuJ7RXMqagMZ",
        "outputId": "5dccb591-ae89-4c84-f5d5-46b70341d0de"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "<BarContainer object of 76 artists>"
            ]
          },
          "metadata": {},
          "execution_count": 18
        },
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 640x480 with 1 Axes>"
            ],
            "image/png": "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ETkAAMAkIgcAAJhE5AAAAJOIHAAAYBKRAwAATCJyAACASUQOAAAwicgBAAAmETkAAMAkIgcAAJhE5AAAAJOIHAAAYBKRAwAATCJyAACASUQOAAAwicgBAAAmRYV7AkC4DZ63rtm2/YuzwjATAEB7InLQaREnAIDWEDkAOj2CF0BLiBwAnQYxA6AtuPAYAACYROQAAACTOF0FczilAQCQiBzgtIglAOjcOF0FAABMInIAAIBJRA4AADCJyAEAACYROQAAwCReXQUARpz6isAzfTVge90PEG4cyQEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJNwMEYNapb2on2XhjO96sD18GC///IXKALoY/kAC6Ck5XAQAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgUpsjZ9OmTbruuuuUmJioiIgIrVmzJmS/4zhasGCB+vfvrx49eigjI0N79+4NGXPkyBFNnTpVMTExiouLU3Z2to4dOxYyZufOnbr66qsVHR2tpKQkLVmypNlcVq9erZSUFEVHR2v48OF66aWX2rocAAA6zOB565rd8OVpc+TU1dUpNTVVBQUFLe5fsmSJHn30URUWFmrr1q0655xzlJmZqePHj7tjpk6dqt27d6u4uFhr167Vpk2bdPfdd7v7g8Ggxo0bp0GDBqm8vFwPPPCAFi1apCeffNIds3nzZt18883Kzs7Wjh07NHHiRE2cOFG7du1q65IAAMDn1JnCrc0f0DlhwgRNmDChxX2O4+iRRx7Rvffeq+uvv16S9Ic//EEJCQlas2aNpkyZonfffVdFRUV68803NWrUKEnSY489pmuvvVa//vWvlZiYqBUrVqihoUFPP/20PB6PLrnkElVUVOihhx5yY2jp0qUaP3685syZI0m6//77VVxcrMcff1yFhYVn9MMAAAB2tOs1OZWVlQoEAsrIyHC3xcbGKj09XWVlZZKksrIyxcXFuYEjSRkZGYqMjNTWrVvdMddcc408Ho87JjMzU3v27NGHH37ojvn04zSNaXochOpM5Q0AQHto85Gc1gQCAUlSQkJCyPaEhAR3XyAQUHx8fOgkoqLUp0+fkDHJycnN7qNpX+/evRUIBFp9nJbU19ervr7e/ToYDLZleQDaWUux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DR06VLfeeqv+9re/af369br33nuVk5Mjr9crSZo+fbr++c9/6p577tF7772nJ554Qs8//7xmz57d3ssBAACdVLtfk/Pvf/9bN998sz744AOdd955uuqqq7Rlyxadd955kqSHH35YkZGRmjRpkurr65WZmaknnnjC/f5u3bpp7dq1mjFjhvx+v8455xxNmzZN9913nzsmOTlZ69at0+zZs7V06VINGDBATz31FC8fBwAArnaPnFWrVrW6Pzo6WgUFBSooKDjtmEGDBumll15q9X7GjBmjHTt2nNEcAQCAfXxAJwAAMIkP6Owgp378gdT6RyC0dTwAAGgdR3IAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgUqePnIKCAg0ePFjR0dFKT0/Xtm3bwj0lAABwFujUkfPcc88pLy9PCxcu1FtvvaXU1FRlZmaquro63FMDAABh1qkj56GHHtJdd92l22+/XUOHDlVhYaF69uypp59+OtxTAwAAYRYV7gmcqYaGBpWXl2v+/PnutsjISGVkZKisrKzF76mvr1d9fb37dW1trSQpGAy2+/wa6//XbFswGOy025t+Rh25/WxZa1fbznPb+bfzHNrdbuE57AhN9+s4TusDnU7qP//5jyPJ2bx5c8j2OXPmOKNHj27xexYuXOhI4saNGzdu3LgZuB08eLDVVui0R3LOxPz585WXl+d+3djYqCNHjqhv376KiIjokMcMBoNKSkrSwYMHFRMT0yGPcbZgrXZ1pfV2pbVK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R5Lz0EMPOTt27HD+9a9/OY7jOIsXL3bi4uKcP//5z87OnTud66+/3klOTnY++uijMM+87WbMmOHExsY6GzdudA4fPuze/ve//7ljpk+f7gwcONDZsGGDs337dsfv9zt+vz+Msz4z8+bNc0pLS53Kykpn586dzrx585yIiAjnlVdecRzHzjpP59OvrnIcW+v90Y9+5GzcuNGprKx03njjDScjI8Pp16+fU11d7TiOrbU6juNs27bNiYqKcn7xi184e/fudVasWOH07NnT+eMf/+iOsfR76uTJk87AgQOduXPnNttn7bltKyKnAz322GPOwIEDHY/H44wePdrZsmVLuKfULl577TVHUrPbtGnTHMf55OWZP/3pT52EhATH6/U6Y8eOdfbs2RPeSZ+hltYpyXnmmWfcMR999JHz/e9/3+ndu7fTs2dP54YbbnAOHz4cvkmfoTvuuMMZNGiQ4/F4nPPOO88ZO3asGziOY2edp3Nq5Fha70033eT079/f8Xg8zle+8hXnpptucvbt2+fut7TWJi+++KIzbNgwx+v1OikpKc6TTz4Zst/S76n169c7klqcv8Xnti0iHMdxwnIICQAAoANxTQ4AADCJyAEAACYROQAAwCQiBwAAmETkAAAAk4gcAABgEpEDAABMInIAAIBJRA4AADCJyAEAACYROQAAwCQiBwAAmPT/AGeMSnw11q6AAAAAAElFTkSuQmCC\n"
          },
          "metadata": {}
        }
      ],
      "source": [
        "# show the link flow as bars\n",
        "plt.bar(range(ntw.num_links), x)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pooE1q35agMZ"
      },
      "source": [
        "`TNTP` モジュールには上述の手続きで均衡解を求めるための関数 `SolveUE` が用意されている．\n",
        "`x = TNTP.SolveUE()` : 均衡フロー・パターンを求め `x` に代入する\n",
        "`x, (Z, Z_rate, x_rate, pi_rate) = TNTP.SolveUE(return_log=True)` : 均衡フロー・パターンのみならず，目的関数`Z`, 目的関数の変化率`Z_rate`, リンク・フローの変化率`x_rate`, 最小所要時間の変化率`pi_rate` を返す\n",
        "`x, (Z, Z_rate, x_rate, pi_rate) = ntw.SolveUE(TNTP.FW_Param(1000, 1e-7, 1e-6, 1e-6), return_log=True)`: `FW_Param`型でFrank-Wolfe法用のパラメータを与える．\n",
        "\n",
        "Frank-Wolfe用のパラメータ・クラス`TNTP.FW_Param`は，以下の書式で初期化される:\n",
        "```\n",
        "TNTP.FW_Param(max_itr, TOL_Z_rate, TOL_x_rate, TOL_pi_rate)\n",
        "```\n",
        "ここで，\n",
        "- `max_itr` : 繰返し回数の最大値\n",
        "- `TOL_Z_rate` : 目的関数の変化率がこの値を下回れば収束と判定($\\epsilon_Z$)\n",
        "- `TOL_x_rate` : リンク・フローの変化率がこの値を下回れば収束と判定($\\epsilon_x$)\n",
        "- `TOL_pi_rate` : ノード間最小旅行時間の変化率がこの値を下回れば収束と判定($\\epsilon_{\\pi}$)"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.7"
    },
    "colab": {
      "provenance": [],
      "include_colab_link": true
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}