Added specification and rules

docs/SPECIFICATION.md

@@ -0,0 +1,229 @@
+# Assignment Specification
+
+Below is the assignment specification, in full, slightly edited for context and
+appearence.
+
+---
+
+## Part 1 - Valid table
+
+Write a function comp10001huxxy_valid_table() which takes a single argument:
+
+- groups, a list of lists of cards (each a 2-element string, where the first
+  letter is the card value and the second letter is the card suit, e.g. '3H' for
+  the 3 of Hearts), where each list of cards represents a single group on the
+  table, and the combined list of lists represents the combined groups played to
+  the table.
+
+Your function should return a bool, which evaluates whether the table state is
+valid or not. Recall from the rules of the game that the table is valid if all
+groups are valid, where a group can take one of the following two forms:
+
+- an N-of-a-kind (i.e. three or more cards of the same value), noting that in
+  the case of a 3-of-a-kind, each card must have a unique suit (e.g. ['2S',
+  '2S', '2C'] is not a valid 3-of-a-kind, as the Two of Spades has been played
+  twice), and if there are 4 or more cards, all suits must be present.
+- a run (i.e. a group of 3 or more cards, starting from the lowest-valued card,
+  and ending with the highest-valued card, forming a continuous sequence in
+  terms of value, and alternating in colour; note that the specific ordering of
+  cards in the list is not significant, i.e. ['2C', '3D', '4S'] and ['4S', '2C',
+  '3D'] both make up the same run.
+
+Example function calls are as follows:
+
+    >>> comp10001huxxy_valid_table([])
+
+    True
+
+    >>> comp10001huxxy_valid_table([['AC']])
+
+    False
+
+    >>> # run too short
+    >>> comp10001huxxy_valid_table([['AC', '2S']])
+
+    False
+
+    >>> # run doesn't alternate in colour
+    >>> comp10001huxxy_valid_table([['AC', '2S', '3H']])
+
+    False
+
+    >>> # values not adjacent
+    >>> comp10001huxxy_valid_table([['AC', '2S', '4H']]) 
+
+    False
+
+    >>> comp10001huxxy_valid_table([['AC', '2H', '3S']])
+
+    True
+
+    >>> # test unsorted run
+    >>> comp10001huxxy_valid_table([['3C', 'AS', '2H']])
+
+    True
+
+    >>> comp10001huxxy_valid_table([['0C', 'JH', 'QS', 'KH', '9D']])
+
+    True
+
+    >>> # n-of-kind too short
+    >>> comp10001huxxy_valid_table([['2C', '2H']])
+
+    False
+
+    >>> # same suit twice for 3-of-kind
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2C']])
+
+    False
+
+    >>> # same suit twice for 4-of-kind
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2S', '2C']])
+
+    False
+
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2S']])
+
+    True
+
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2S', '2D']])
+
+    True
+
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2S', '2D', '2S']])
+
+    True
+
+    >>> comp10001huxxy_valid_table([['2C', '2H', '2S', '2D', '2S'], ['0D', '9C', '8H']])
+
+    True
+
+## Part 2 - Group validation
+
+Write a function comp10001go_valid_groups() which takes a single argument:
+
+- groups, a list of groups, each of which is a list of cards (following the same
+  definition as Part 1)
+
+Your function should return a Boolean indicating whether all groups are valid or
+not (i.e. a singleton card, a valid N-of-a-kind or a valid run). Note that the
+function may be used to validate a grouping of partial discards or the full set
+of discards, i.e. the total number of cards in groups will be between 0 and 10.
+
+Example function calls are as follows:
+
+    >>> comp10001go_valid_groups([['KC', 'KH', 'KS', 'KD'], ['2C']])
+
+    True
+
+    >>> comp10001go_valid_groups([['KC', 'KH', 'KS', 'AD'], ['2C']])
+
+    False
+
+    >>> comp10001go_valid_groups([['KC', 'KH', 'KS', 'KD'], ['2C', '3H']])
+
+    False
+
+    >>> comp10001go_valid_groups([])
+
+    True
+
+## Part 3 - Play and Group
+
+The third question requires that you implement the two functions that are called
+in the tournament: (1) comp10001_play, which is used to select a discard over
+the 10 turns of a game; and (2) comp10001_group, which is used to group the
+discards into groups for scoring. We combine these together into a single
+question in Grok as a means of validating that you have a complete player that
+is qualified to enter the tournament. Note that in each case, we provide only a
+single test case (and no hidden test cases) for two reasons: (1) there are very
+few game states where there is a single possible option to either play a discard
+or group the discards, and testing relies on there only being one possible
+output; and (2) the real testing occurs in simulation mode in the actual
+tournament, in the form of random games against other players. On validation of
+implementations of each of the two functions, you will be given the option to
+submit your player to the tournament.
+
+First, write a function comp10001go_play() which takes three arguments:
+
+- discard_history, a list of lists of four cards, each representing the discards
+  from each of the four players in preceding turns (up to 9 turns) in sequence
+  of player number (i.e. the first element in each list of four cards is for
+  Player 0, the second is for Player 1, etc.). Note that the list is sequenced
+  based on the turns, i.e. the first list of four cards corresponds to the first
+  turn, and the last list of four cards corresponds to the last turn.
+- player_no, an integer between 0 and 3 inclusive, indicating which player is
+  being asked to play. player_no can also be used to determine the discards for
+  that player from discard_history by indexing within each list of four cards.
+- hand, a list of cards held by the player.
+
+Your function should return a single card to discard from hand.
+
+An example function call is as follows:
+
+    >>> comp10001go_play([['0S', 'KH', 'AC', '3C'], ['JH', 'AD', 'QS', '5H'], ['9C', '8S', 'QH', '9S'], ['8C', '9D', '0D', 'JS'], ['5C', 'AH', '5S', '4C'], ['8H', '2D', '6C', '2C'], ['8D', '4D', 'JD', 'AS'], ['0H', '6S', '2H', 'KC'], ['KS', 'KD', '7S', '6H']], 3, ['QC'])
+
+    'QC'
+
+Second, write a function comp10001go_group() which takes two arguments:
+
+- discard_history, a list of lists of four cards, each representing the discards
+  from each of the four players in preceding turns in sequence of player number
+  (i.e., the first element in each list of four cards is for Player 0, the
+  second is for Player 1, etc.). Note that the list is sequenced based on the
+  turns, i.e. the first list of four cards corresponds to the first turn, and
+  the last list of four cards corresponds to the last turn. Additionally note
+  that the number of turns contained in discard_history will always be 10.
+- player_no, an integer between 0 and 3 inclusive, indicating which player is
+  being asked to play. player_no can also be used to determine the discards for
+  that player from discard_history by indexing within each list of four cards.
+
+Your function should return a list of lists of cards based on the discard
+history of player_no, to use in scoring the player. Note that the grouping of
+cards represented by the output must be valid (i.e. each list of cards must be a
+singleton card, or a valid N-of-a-kind or run), but that the ordering of cards
+within groups, and the ordering of groups is not significant.
+
+An example function call is as follows:
+
+    >>> comp10001go_group([['0S', 'KH', 'AC', '3C'], ['JH', 'AD', 'QS', '5H'], ['9C', '8S', 'QH', '9S'], ['8C', '9D', '0D', 'JS'], ['5C', 'AH', '5S', '4C'], ['8H', '2D', '6C', '2C'], ['8D', '4D', 'JD', 'AS'], ['0H', '6S', '2H', 'KC'], ['KS', 'KD', '7S', '6H'], ['JC', 'QD', '4H', 'QC']], 3)
+
+    [['3C'], ['5H'], ['9S'], ['JS'], ['4C'], ['2C'], ['AS'], ['KC'], ['6H'], ['QC']]
+
+## Part 4 - Optimal grouping
+
+The final question is for bonus marks, and is deliberately quite a bit harder
+than the four basic questions (and the number of marks on offer is, as always,
+deliberately not commensurate with the amount of effort required). Only attempt
+this is you have completed the earlier questions, and are up for a challenge!
+
+Write a function comp10001go_best_partitions() which takes a single argument:
+
+- cards, a list of up to 10 cards
+
+Your function should return a list of list of lists of cards, representing the
+groupings of cards that score the most points from cards. Note that the ordering
+of the groupings is not significant, and neither is the ordering of the groups
+within a grouping, nor the order of cards within a group.
+
+One area of particular focus with this question is efficiency: there are strict
+time limits associated with running your code over each example, that you must
+work within, or you will fail the test. Good luck!
+
+Example function calls are as follows:
+
+    >>> comp10001go_best_partitions(['0H', '8S', '6H', 'AC', '0S', 'JS', '8C', '7C', '6D', 'QS'])
+
+    [[['AC'], ['0H', '0S'], ['JS'], ['8S', '8C'], ['7C'], ['6H', '6D'], ['QS']]]
+
+    >>> comp10001go_best_partitions(['9D', '2S', '4D', '4H', '6D', 'AH', '2C', 'JH', '3C', '9H'])
+
+    [[['4D', '4H'], ['6D'], ['AH'], ['2S', '2C'], ['JH'], ['3C'], ['9D', '9H']]]
+
+    >>> comp10001go_best_partitions(['3C', '5H', '9S', 'JS', '4C', '2C', 'AS', 'KC', '6H', 'QC'])
+
+    [[['3C'], ['5H'], ['9S'], ['JS'], ['4C'], ['2C'], ['AS'], ['KC'], ['6H'], ['QC']]]
+
+    >>> comp10001go_best_partitions(['0D', 'AS', '5C', '8H', 'KS', 'AH', 'QH', 'AC'])
+
+    [[['AS', '5C', '8H', 'AH'], ['0D', 'KS', 'QH', 'AC']], [['0D', 'AS', 'KS', 'QH'], ['5C', '8H', 'AH', 'AC']]]