You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
224 lines
11 KiB
224 lines
11 KiB
//==============================================================================
|
|
//
|
|
// Copyright (c) 2002-
|
|
// Authors:
|
|
// * Dave Parker <david.parker@comlab.ox.ac.uk> (University of Oxford)
|
|
//
|
|
//------------------------------------------------------------------------------
|
|
//
|
|
// This file is part of PRISM.
|
|
//
|
|
// PRISM 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.
|
|
//
|
|
// PRISM 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.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with PRISM; if not, write to the Free Software Foundation,
|
|
// Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
//
|
|
//==============================================================================
|
|
|
|
package explicit;
|
|
|
|
import java.util.BitSet;
|
|
import java.util.Iterator;
|
|
import java.util.List;
|
|
import java.util.Map.Entry;
|
|
|
|
import explicit.rewards.STPGRewards;
|
|
|
|
/**
|
|
* Interface for classes that provide (read) access to an explicit-state stochastic two-player game (STPG).
|
|
* <br><br>
|
|
* These are turn-based STPGs, i.e. at most one player controls each state.
|
|
* Probabilistic states do not need to be stored explicitly; instead, like in an MDP,
|
|
* players have several 'choices', each of which is a probability distribution over successor states.
|
|
* <br><br>
|
|
* For convenience/efficiency, STPGs can actually store two transitions/choices in two ways.
|
|
* The first is as described above: a state has a list of choices which are distributions over states.
|
|
* {@link #getNumChoices(s)} gives the number of choices, {@link #getAction(s)} gives an (optional) action label
|
|
* for each one and {@link #getTransitionsIterator(s, i)} provides an iterator over target-state/probability pairs.
|
|
* The second way is 'nested' choices: the choices in a state are instead transitions directly to states of the other player.
|
|
* Each of those states then has has several choices that are distributions over states, as above.
|
|
* The middle layer of states are not stored explicitly, however. If the {@code i}th choice of state {@code s}
|
|
* is nested in this way, then {@link #isChoiceNested(s, i)} is true and {@link #getTransitionsIterator(s, i)} returns null.
|
|
* Use {@link #getNumNestedChoices(s, i)}, {@link #getNestedAction(s, i)} and {@link #getNestedTransitionsIterator(s, i, j)}
|
|
* to access the information.
|
|
*/
|
|
public interface STPG extends NondetModel
|
|
{
|
|
/**
|
|
* Get the player that owns state {@code s} (1 or 2 for an STPG).
|
|
*/
|
|
public int getPlayer(int s);
|
|
|
|
/**
|
|
* Get the number of transitions from choice {@code i} of state {@code s}.
|
|
*/
|
|
public int getNumTransitions(int s, int i);
|
|
|
|
/**
|
|
* Get an iterator over the transitions from choice {@code i} of state {@code s}.
|
|
*/
|
|
public Iterator<Entry<Integer, Double>> getTransitionsIterator(int s, int i);
|
|
|
|
/**
|
|
* Is choice {@code i} of state {@code s} in nested form? (See {@link explicit.STPG} for details)
|
|
*/
|
|
public boolean isChoiceNested(int s, int i);
|
|
|
|
/**
|
|
* Get the number of (nested) choices in choice {@code i} of state {@code s}.
|
|
*/
|
|
public int getNumNestedChoices(int s, int i);
|
|
|
|
/**
|
|
* Get the action label (if any) for nested choice {@code i,j} of state {@code s}.
|
|
*/
|
|
public Object getNestedAction(int s, int i, int j);
|
|
|
|
/**
|
|
* Get the number of transitions from nested choice {@code i,j} of state {@code s}.
|
|
*/
|
|
public int getNumNestedTransitions(int s, int i, int j);
|
|
|
|
/**
|
|
* Get an iterator over the transitions from nested choice {@code i,j} of state {@code s}.
|
|
*/
|
|
public Iterator<Entry<Integer, Double>> getNestedTransitionsIterator(int s, int i, int j);
|
|
|
|
/**
|
|
* Perform a single step of precomputation algorithm Prob0, i.e., for states i in {@code subset},
|
|
* set bit i of {@code result} iff, for all/some player 1 choices, for all/some player 2 choices,
|
|
* there is a transition to a state in {@code u}.
|
|
* Quantification over player 1/2 choices is determined by {@code forall1}, {@code forall2}.
|
|
* @param subset Only compute for these states
|
|
* @param u Set of states {@code u}
|
|
* @param forall1 For-all or there-exists for player 1 (true=for-all, false=there-exists)
|
|
* @param forall2 For-all or there-exists for player 2 (true=for-all, false=there-exists)
|
|
* @param result Store results here
|
|
*/
|
|
public void prob0step(BitSet subset, BitSet u, boolean forall1, boolean min2, BitSet result);
|
|
|
|
/**
|
|
* Perform a single step of precomputation algorithm Prob1, i.e., for states i in {@code subset},
|
|
* set bit i of {@code result} iff, for all/some player 1 choices, for all/some player 2 choices,
|
|
* there is a transition to a state in {@code v} and all transitions go to states in {@code u}.
|
|
* Quantification over player 1/2 choices is determined by {@code forall1}, {@code forall2}.
|
|
* @param subset Only compute for these states
|
|
* @param u Set of states {@code u}
|
|
* @param v Set of states {@code v}
|
|
* @param forall1 For-all or there-exists for player 1 (true=for-all, false=there-exists)
|
|
* @param forall2 For-all or there-exists for player 2 (true=for-all, false=there-exists)
|
|
* @param result Store results here
|
|
*/
|
|
public void prob1step(BitSet subset, BitSet u, BitSet v, boolean min1, boolean min2, BitSet result);
|
|
|
|
/**
|
|
* Do a matrix-vector multiplication followed by two min/max ops, i.e. one step of value iteration,
|
|
* i.e. for all s: result[s] = min/max_{k1,k2} { sum_j P_{k1,k2}(s,j)*vect[j] }
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param result Vector to store result in
|
|
* @param subset Only do multiplication for these rows (ignored if null)
|
|
* @param complement If true, {@code subset} is taken to be its complement (ignored if {@code subset} is null)
|
|
* @param adv Storage for adversary choice indices (ignored if null)
|
|
*/
|
|
public void mvMultMinMax(double vect[], boolean min1, boolean min2, double result[], BitSet subset, boolean complement, int adv[]);
|
|
|
|
/**
|
|
* Do a single row of matrix-vector multiplication followed by min/max,
|
|
* i.e. return min/max_{k1,k2} { sum_j P_{k1,k2}(s,j)*vect[j] }
|
|
* @param s Row index
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
*/
|
|
public double mvMultMinMaxSingle(int s, double vect[], boolean min1, boolean min2);
|
|
|
|
/**
|
|
* Determine which choices result in min/max after a single row of matrix-vector multiplication.
|
|
* @param s Row index
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param val Min or max value to match
|
|
*/
|
|
public List<Integer> mvMultMinMaxSingleChoices(int s, double vect[], boolean min1, boolean min2, double val);
|
|
|
|
/**
|
|
* Do a Gauss-Seidel-style matrix-vector multiplication followed by min/max.
|
|
* i.e. for all s: vect[s] = min/max_{k1,k2} { (sum_{j!=s} P_{k1,k2}(s,j)*vect[j]) / P_{k1,k2}(s,s) }
|
|
* and store new values directly in {@code vect} as computed.
|
|
* The maximum (absolute/relative) difference between old/new
|
|
* elements of {@code vect} is also returned.
|
|
* @param vect Vector to multiply by (and store the result in)
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param subset Only do multiplication for these rows (ignored if null)
|
|
* @param complement If true, {@code subset} is taken to be its complement (ignored if {@code subset} is null)
|
|
* @param absolute If true, compute absolute, rather than relative, difference
|
|
* @return The maximum difference between old/new elements of {@code vect}
|
|
*/
|
|
public double mvMultGSMinMax(double vect[], boolean min1, boolean min2, BitSet subset, boolean complement, boolean absolute);
|
|
|
|
/**
|
|
* Do a single row of Jacobi-style matrix-vector multiplication followed by min/max.
|
|
* i.e. return min/max_{k1,k2} { (sum_{j!=s} P_{k1,k2}(s,j)*vect[j]) / P_{k1,k2}(s,s) }
|
|
* @param s Row index
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
*/
|
|
public double mvMultJacMinMaxSingle(int s, double vect[], boolean min1, boolean min2);
|
|
|
|
/**
|
|
* Do a matrix-vector multiplication and sum of action reward followed by min/max, i.e. one step of value iteration.
|
|
* i.e. for all s: result[s] = min/max_{k1,k2} { rew(s) + sum_j P_{k1,k2}(s,j)*vect[j] }
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param result Vector to store result in
|
|
* @param subset Only do multiplication for these rows (ignored if null)
|
|
* @param complement If true, {@code subset} is taken to be its complement (ignored if {@code subset} is null)
|
|
* @param adv Storage for adversary choice indices (ignored if null)
|
|
*/
|
|
public void mvMultRewMinMax(double vect[], STPGRewards rewards, boolean min1, boolean min2, double result[], BitSet subset, boolean complement, int adv[]);
|
|
|
|
/**
|
|
* Do a single row of matrix-vector multiplication and sum of action reward followed by min/max.
|
|
* i.e. return min/max_{k1,k2} { rew(s) + sum_j P_{k1,k2}(s,j)*vect[j] }
|
|
* @param s Row index
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param adv Storage for adversary choice indices (ignored if null)
|
|
*/
|
|
public double mvMultRewMinMaxSingle(int s, double vect[], STPGRewards rewards, boolean min1, boolean min2, int adv[]);
|
|
|
|
/**
|
|
* Determine which choices result in min/max after a single row of matrix-vector multiplication and sum of action reward.
|
|
* @param s Row index
|
|
* @param vect Vector to multiply by
|
|
* @param min1 Min or max for player 1 (true=min, false=max)
|
|
* @param min2 Min or max for player 2 (true=min, false=max)
|
|
* @param val Min or max value to match
|
|
*/
|
|
public List<Integer> mvMultRewMinMaxSingleChoices(int s, double vect[], STPGRewards rewards, boolean min1, boolean min2, double val);
|
|
|
|
/**
|
|
* Checks whether all successors of action c in state s are in a given set
|
|
* @param s state
|
|
* @param c choice
|
|
* @param set target set
|
|
* @return true if all successors are, false otherwise
|
|
*/
|
|
public boolean allSuccessorsInSet(int s, int c, BitSet set);
|
|
}
|