.. _gambit-hp:

:program:`gambit-hp`
=====================

Compute a Nash equilibrium in a strategic game using the homotopy method of
:cite:t:`HerPee01`.

The algorithm finds one equilibrium starting from any given prior
distribution over strategies, which must have a unique best response for
each player.  Multiple prior distributions may be generated via the `-n`
option or specified via the `-s` option; different priors may result in
different equilibria being found.


.. program:: gambit-hp

.. cmdoption:: -d

   Express all output using decimal representations
   with the specified number of digits.

.. cmdoption:: -h

   Prints a help message listing the available options.

.. cmdoption:: -m

   Specify the maximum regret criterion for acceptance as an approximate Nash equilibrium
   (default is 1e-8).  See :ref:`pygambit-nash-maxregret` for interpretation and guidance.

.. cmdoption:: -n

   Randomly generate the specified number of prior distributions.
   Mutually exclusive with :option:`-s`.

.. cmdoption:: -R

   Seeds the random number generator used to generate prior
   distributions with the specified value, so that the sequence of priors
   generated by :option:`-n` can be reproduced across runs.  If not
   specified, the generator is seeded from system entropy.  Requires
   :option:`-n`.

.. cmdoption:: -q

   Suppresses printing of the banner at program launch.

.. cmdoption:: -s

   Specifies a file containing a list of prior distributions over
   strategies. The format of the file is comma-separated values,
   one mixed strategy profile per line, in the same format used for
   output of equilibria (excluding the initial NE tag).
   Mutually exclusive with :option:`-n`.

.. cmdoption:: -V, --verbose

   Show the prior distribution itself, tagged `prior`, followed by each
   point traced along the homotopy path, tagged with the homotopy
   parameter t in place of the NE tag.  Note that the point at t=0 is the
   best response to the prior, and so is generally a pure strategy profile
   even when the prior itself is not.  If this option is not specified,
   only the equilibrium found is reported.

.. cmdoption:: -v, --version

   Prints version information and exits.


Computing an equilibrium of the reduced strategic form of the example in
Figure 2 of :cite:p:`Sel75`, starting from the prior in which player 1
plays (0.5, 0.3, 0.2) and player 2 plays (0.6, 0.4)::

   $ echo "0.5,0.3,0.2,0.6,0.4" > prior.csv
   $ gambit-hp -s prior.csv catalog/games/journals/ijgt/selten1975/fig2.efg
   Compute a Nash equilibrium using the Herings-Peeters (2001) homotopy method
   Gambit version |release|, Copyright (C) 1994-2026, The Gambit Project
   This is free software, distributed under the GNU GPL

   NE,1.000000,0.000000,0.000000,0.999976,0.000024