//============================================================================== // // Copyright (c) 2002- // Authors: // * Dave Parker (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). *

* 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. *

* 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> 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> 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 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 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); }