Package Guide

The code base is organized into several modules for ease of access and use. The main module is contained under the src directory, which contains the solver. It is written for julia 1.9.1, which can be installed and managed using the juliaup tool.

Detailed examples for use can be found in several experiments, each with a dedicated directory under the exp folder. The solver primarily supports calling the function solve_myopic_inverse_game(...). The second through third required arguments observed_trajectory, observation_model, hidden_state_dim are easy to construct without specific tools.

observed_trajectory should be a 2D vector of the same length as the horizon of the game and each element being an observation of the state. The inverse game solver will produce an estimation of game parameters so that the resulting game trajectory is most likely to have produced the input observations.

observation_model should be a function that takes in a state and produces an observation of the state. The observed_trajectory should be generated from this function.

hidden_state_dim should be a vector whose elements correspond to the length of the parameters to estimate for each player. For example, if player 1 has 4 related parameters to estimate and player 2 has 5 parameters, then the input should be [4, 5].

Finally, the first argument, mcp_game, is most easily constructed through functions provided - namely, MCPGame and MCPCoupledOptimizationSolver. These return data structures in the format expected by our solver and contain game theoretic games as well as the associated mixed complimentarity problem.

Recreating Experiments

For this repo, we need Julia 1.9.1. This can be done using Julia manager Juliaup, which should come installed with most common methods of installing Julia. We can add Julia 1.9.1 by running juliaup add 1.9.1, which should show:

$ juliaup add 1.9.1
Checking for new Julia versions
Installing Julia 1.9.1+0.x64.linux.gnu

when completed. Next, we navigate to the directory containing this repo, and use julia +1.9.1 --proj to start Julia with version 1.9.1 and with the current project activated. Then, the project dependencies can be instantiated by typing ] in the Julia REPL. The terminal should at this point show:

$ julia +1.9.1 --proj
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.9.1 (2023-06-07)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

(InverseGameDiscountFactor) pkg> 

From here, we simply type instantiate, and the Julia package manager will automatically install dependencies.

The basic results of the experiments can be recreated by running functions in the exp directory. Specifically, the experiments directory contains a folder with a julia file that has the same name. For example, exp/crosswalk/Crosswalk.jl has a function run_myopic_crosswalk_sim(;...), which can be run from the REPL:

julia> include("./experiments/crosswalk/Crosswalk.jl")

After which we can run:

julia> Crosswalk.run_myopic_crosswalk_sim()

This will recreate the simplest "proof of concept" experiment present in the earliest versions of the paper. The results can be seen in the output plots.

Other experiments, such as the In-D data experiment, can be run:

julia> include("experiments/In-D/InD.jl")
julai> InD.compare_to_baseline()

This will produce terminal output as well as plots.

Finally, the Waymax simulation is run in python, rather than julia. In order to do this, there is a conda environment setup script run by setup_environment.sh in the top-level directory.

The dataset is too large to download locally, so we have set up a script experiments/waymax/find_scenario.py to iterate through the many scenarios provided by Waymo. Our paper uses the second scenario, or the scenario saved as experiments/wayamx/data/scenario_iter_1.pkl. Then, the actual scenario (with the baseline solver) can be run by calling:

$ python ./experiments/waymax/run_sim.py

To run our method, simply add the -m flag:

$ python experiments/waymax/run_sim.py -m

Note that there are known issues with using Julia from Python on a Windows environment. If possible, please run from a Linux environment. Otherwise, there may be many issues with how Python package managers such as conda interact with Julia.