sudoku

type Cell interface {
	//Row returns the cell's row in its parent grid.
	Row() int

	//Col returns the cell's column in its parent grid.
	Col() int

	//Block returns the cell's block in its parent grid.
	Block() int

	//InGrid returns a reference to a cell in the provided grid that has the same
	//row/column as this cell. Effectively, this cell's analogue in the other
	//grid.
	InGrid(grid Grid) Cell

	//MutableInGrid is like InGrid, but will only work on grids that are mutable.
	MutableInGrid(grid MutableGrid) MutableCell

	//Number returns the number the cell is currently set to.
	Number() int

	//Mark reads out whether the given mark has been set for this cell. See
	//SetMark for a description of what marks represent.
	Mark(number int) bool

	//Marks returns an IntSlice with each mark, in ascending order.
	Marks() IntSlice

	//Possible returns whether or not a given number is legal to fill via
	//SetNumber, given the state of the grid (specifically, the cell's neighbors)
	//and the numbers the cell was told to explicitly exclude via SetExclude. If
	//the cell is already filled with a number, it will return false for all
	//numbers.
	Possible(number int) bool

	//Possibilities returns a list of all current possibilities for this cell: all
	//numbers for which cell.Possible returns true.
	Possibilities() IntSlice

	//Excluded returns whether or not the given number has been specifically
	//excluded with SetExcluded.
	Excluded(number int) bool

	//Invalid returns true if the cell has no valid possibilities to fill in,
	//implying that the grid is in an invalid state because this cell cannot be
	//filled with a number without violating a constraint.
	Invalid() bool

	//Locked returns whether or not the cell is locked. See Lock for more
	//information on the concept of locking.
	Locked() bool

	//SymmetricalPartner returns the cell's partner in the grid, based on the type
	//of symmetry requested.
	SymmetricalPartner(symmetry SymmetryType) Cell

	//Neighbors returns a CellSlice of all of the cell's neighbors--the other
	//cells in its row, column, and block. The set of neighbors is the set of
	//cells that this cell's number must not conflict with.
	Neighbors() CellSlice

	//String returns a debug-friendly summary of the Cell.
	String() string

	//DiagramExtents returns the top, left, height, and width coordinate in
	//grid.Diagram's output that  corresponds to the contents of this cell. The
	//top left corner is 0,0
	DiagramExtents() (top, left, height, width int)

	//Grid returns a reference to the Grid that this Cell is associated with.
	Grid() Grid

	//Reference returns a CellReference corresponding to this cell.
	Reference() CellRef
	// contains filtered or unexported methods
}

type CellModification struct {
	//The cell representing the cell to modify. The cell's analog (at the same
	//row, col address) will be modified in the new grid.
	Cell CellRef
	//The number to put in the cell. Negative numbers signify no changes.
	Number int
	//The excludes to proactively set. Invalid numbers will be ignored.
	//Indexes not listed will be left the same.
	ExcludesChanges map[int]bool
	//The marks to proactively set. Invalid numbers will be ignored.
	//Indexes not listed will be left the same.
	MarksChanges map[int]bool
}

type CellRef struct {
	Row int
	Col int
}

type CellRefSlice []CellRef

type CellSlice []Cell

type CompoundSolveStep struct {
	PrecursorSteps []*SolveStep
	FillStep       *SolveStep
	// contains filtered or unexported fields
}

type DifficultySignals map[string]float64

type GenerationOptions struct {
	//symmetrty and symmetryType control the aesthetics of the generated grid. symmetryPercentage
	//controls roughly what percentage of cells with have a filled partner across the provided plane of
	//symmetry.
	Symmetry           SymmetryType
	SymmetryPercentage float64
	//The minimum number of cells to leave filled in the puzzle. The generated puzzle might have
	//more filled cells. A value of DIM * DIM - 1, for example, would return an extremely trivial
	//puzzle.
	MinFilledCells int
}

type Grid interface {

	//Copy returns a new immutable grid that has all of the same observable
	//state (including set numbers, locks, excludes, marks, etc)
	Copy() Grid

	//MutableCopy returns a new, mutable grid that has all of the same
	//starting state (including set numbers, locks, excludes, marks, etc.)
	MutableCopy() MutableGrid

	//CopyWithModifications returns a new immutable Grid that has the given
	//modifications applied.
	CopyWithModifications(modifications GridModification) Grid

	//Cells returns a CellSlice with pointers to every cell in the grid,
	//from left to right and top to bottom.
	Cells() CellSlice

	//Row returns a CellSlice containing all of the cells in the given row (0
	//indexed), in order from left to right.
	Row(index int) CellSlice

	//Col returns a CellSlice containing all of the cells in the given column (0
	//indexed), in order from top to bottom.
	Col(index int) CellSlice

	//Block returns a CellSlice containing all of the cells in the given block (0
	//indexed), in order from left to right, top to bottom.
	Block(index int) CellSlice

	//Cell returns a reference to a specific cell (zero-indexed) in the grid.
	Cell(row, col int) Cell

	//Solved returns true if all cells are filled without violating any
	//constraints; that is, the puzzle is solved.
	Solved() bool

	//Invalid returns true if any numbers are set in the grid that conflict with
	//numbers set in neighborhing cells; when a valid solution cannot be arrived
	//at by continuing to fill additional cells.
	Invalid() bool

	//Empty returns true if none of the grid's cells are filled.
	Empty() bool

	//DataString represents the serialized format of the grid (not including
	//excludes) in canonical sdk format; the output is valid to pass to
	//Grid.Load(). If you want other formats, see the sdkconverter subpackage.
	DataString() string

	//String returns a concise representation of the grid appropriate for printing
	//to the screen. Currently simply an alias for DataString.
	String() string

	//Diagram returns a verbose visual representation of a grid, representing not
	//just filled numbers but also what numbers in a cell are possible. If
	//showMarks is true, instead of printing the possibles, it will print only the
	//activley added marks.
	Diagram(showMarks bool) string

	//HumanSolution returns the SolveDirections that represent how a human
	//would solve this puzzle. If options is nil, will use reasonable
	//defaults.
	HumanSolution(options *HumanSolveOptions) *SolveDirections

	//Hint returns a SolveDirections with precisely one CompoundSolveStep that is
	//a reasonable next step to move the puzzle towards being completed. It is
	//effectively a hint to the user about what Fill step to do next, and why it's
	//logically implied; the truncated return value of HumanSolve. Returns nil if
	//the puzzle has multiple solutions or is otherwise invalid. If options is
	//nil, will use reasonable defaults. optionalPreviousSteps, if provided,
	//serves to help the algorithm pick the most realistic next steps.
	Hint(options *HumanSolveOptions, optionalPreviousSteps []*CompoundSolveStep) *SolveDirections

	//Difficulty returns a value between 0.0 and 1.0, representing how hard the
	//puzzle would be for a human to solve. :This is an EXTREMELY expensive method
	//(although repeated calls without mutating the grid return a cached value
	//quickly). It human solves the puzzle, extracts signals out of the
	//solveDirections, and then passes those signals into a machine-learned model
	//that was trained on hundreds of thousands of solves by real users in order
	//to generate a candidate difficulty. It then repeats the process multiple
	//times until the difficultly number begins to converge to an average.
	Difficulty() float64

	//NumSolutions returns the total number of solutions found in the grid when it
	//is solved forward from this point. A valid Sudoku puzzle has only one
	//solution.
	NumSolutions() int

	//HasSolution returns true if the grid has at least one solution.
	HasSolution() bool

	//HasMultipleSolutions returns true if the grid has more than one solution.
	HasMultipleSolutions() bool

	//Solutions returns a slice of grids that represent possible solutions if you
	//were to solve forward this grid. The current grid is not modified. If there
	//are no solutions forward from this location it will return a slice with
	//len() 0.
	Solutions() []Grid

	//HumanSolvePossibleSteps returns a list of CompoundSolveSteps that could
	//apply at this state, along with the probability distribution that a human
	//would pick each one. The optional previousSteps argument is the list of
	//CompoundSolveSteps that have been applied to the grid so far, and is used
	//primarily to tweak the probability distribution and make, for example, it
	//more likely to pick cells in the same block as the cell that was just
	//filled. This method is the workhorse at the core of HumanSolve() and is
	//exposed here primarily so users of this library can get a peek at which
	//possibilites exist at each step. cmd/i-sudoku is one user of this method.
	HumanSolvePossibleSteps(options *HumanSolveOptions, previousSteps []*CompoundSolveStep) (steps []*CompoundSolveStep, distribution ProbabilityDistribution)
	// contains filtered or unexported methods
}

type GridModification []*CellModification

type HumanSolveOptions struct {
	//At each step in solving the puzzle, how many candidate SolveSteps should
	//we generate before stopping the search for more? Higher values will give
	//more 'realistic' solves, but at the cost of *much* higher performance
	//costs. Also note that the difficulty may be wrong if the difficulty
	//model in use was trained on a different NumOptionsToCalculate.
	NumOptionsToCalculate int
	//Which techniques to try at each step of the puzzle, sorted in the order
	//to try them out (generally from cheapest to most expensive). A value of
	//nil will use Techniques (the default). Any GuessTechniques will be
	//ignored.
	TechniquesToUse []SolveTechnique
	//NoGuess specifies that even if no other techniques work, the HumanSolve
	//should not fall back on guessing, and instead just return failure.
	NoGuess bool
	// contains filtered or unexported fields
}

type IntSlice []int

type MutableCell interface {
	//MutableCell contains all of Cell's (read-only) methods.
	Cell

	//MutableNeighbors returns a MutableCellSlice of all of the cell's
	//neighbors--the other cells in its row, column, and block. The set of
	//neighbors is the set of cells that this cell's number must not conflict
	//with.
	MutableNeighbors() MutableCellSlice

	//MutableSymmetricalPartner returns the cell's mutable partner in the
	//grid, based on the type of symmetry requested.
	MutableSymmetricalPartner(symmetry SymmetryType) MutableCell

	//SetNumber explicitly sets the number of the cell. This operation could cause
	//the grid to become invalid if it conflicts with its neighbors' numbers. This
	//operation will affect the Possiblities() of its neighbor cells.
	SetNumber(number int)

	//SetExcluded defines whether a possibility is considered not feasible, even
	//if not directly precluded by the Number()s of the cell's neighbors. This is
	//used by advanced HumanSolve techniques that cull possibilities that are
	//logically excluded by the state of the grid, in a non-direct way. The state
	//of Excluded bits will affect the results of this cell's Possibilities()
	//list.
	SetExcluded(number int, excluded bool)

	//ResetExcludes sets all excluded bits to false, so that Possibilities() will
	//be based purely on direct implications of the Number()s of neighbors. See
	//also SetExcluded.
	ResetExcludes()

	//SetMark sets the mark at the given index to true. Marks represent number
	//marks proactively added to a cell by a user. They have no effect on the
	//solver or human solver; they only are visible when Diagram(true) is called.
	SetMark(number int, mark bool)

	//ResetMarks removes all marks. See SetMark for a description of what marks
	//represent.
	ResetMarks()

	//Lock 'locks' the cell. Locking represents the concept of cells that are set
	//at the beginning of the puzzle and that users may not modify. Locking does
	//not change whether calls to SetNumber or SetMark will fail; it only impacts
	//Diagram().
	Lock()

	//Unlock 'unlocks' the cell. See Lock for more information on the concept of
	//locking.
	Unlock()

	//MutableGrid returns a reference to the MutableGrid this MutableCell is
	//associated with.
	MutableGrid() MutableGrid
	// contains filtered or unexported methods
}

type MutableCellSlice []MutableCell

type MutableGrid interface {
	//MutableGrid contains all of Grid's (read-only) methods.
	Grid

	//Load is like the top-level MutableLoad, but mutates this grid as opposed
	//to returning a new one.
	Load(data string)

	//LoadSDK is like the top-level MutableLoadSDK, but mutates this grid as
	//opposed to returning a new one.
	LoadSDK(data string)

	//ResetExcludes calls ResetExcludes on all cells in the grid. See
	//Cell.SetExcluded for more about excludes.
	ResetExcludes()

	//ResetMarks calls ResetMarks on all cells in the grid. See Cell.SetMark for
	//more about marks.
	ResetMarks()

	//ResetUnlockedCells clears out numbers, marks, and excludes from each cell
	//that is unlocked. In general a locked cell represents a number present in
	//the original puzzle, so this method effectively clears all user
	//modifications back to the start of the puzzle.
	ResetUnlockedCells()

	//UnlockCells unlocks all cells. See cell.Lock for more information on the
	//concept of locking.
	UnlockCells()

	//LockFilledCells locks all cells in the grid that have a number set.
	LockFilledCells()

	//MutableCells returns a MutableCellSlice with pointers to every cell in the
	//grid, from left to right and top to bottom.
	MutableCells() MutableCellSlice

	//MutableRow returns a MutableCellSlice containing all of the cells in the
	//girven row (0 indexed), in order from left to right.
	MutableRow(index int) MutableCellSlice

	//MutableCol returns a MutableCellSlice containing all of the cells in the
	//given column (0 indexed), in order from top to bottom.
	MutableCol(index int) MutableCellSlice

	//MutableBlock returns a MutableCellSlice containing all of the cells in the
	//given block (0 indexed), in order from left to right, top to bottom.
	MutableBlock(index int) MutableCellSlice

	//MutableCell returns a reference to a Mutable Cell at the given location.
	MutableCell(row, col int) MutableCell

	//Fill will find a random filling of the puzzle such that every cell is filled
	//and no cells conflict with their neighbors. If it cannot find one,  it will
	//return false and leave the grid as it found it. Generally you would only
	//want to call this on grids that have more than one solution (e.g. a fully
	//blank grid). Fill provides a good starting point for generated puzzles.
	Fill() bool

	//HumanSolve is the workhorse of the package. It solves the puzzle much like a
	//human would, applying complex logic techniques iteratively to find a
	//sequence of steps that a reasonable human might apply to solve the puzzle.
	//HumanSolve is an expensive operation because at each step it identifies all
	//of the valid logic rules it could apply and then selects between them based
	//on various weightings. HumanSolve endeavors to find the most realistic human
	//solution it can by using a large number of possible techniques with
	//realistic weights, as well as by doing things like being more likely to pick
	//a cell that is in the same row/cell/block as the last filled cell. Returns
	//nil if the puzzle does not have a single valid solution. If options is nil,
	//will use reasonable defaults. Mutates the grid.
	HumanSolve(options *HumanSolveOptions) *SolveDirections

	//Solve searches for a solution to the puzzle as it currently exists
	//without unfilling any cells. If one exists, it will fill in all cells to
	//fit that solution and return true. If there are no solutions the grid
	//will remain untouched and it will return false. If multiple solutions
	//exist, Solve will pick one at random.
	Solve() bool
	// contains filtered or unexported methods
}

type ProbabilityDistribution []float64

type SolveDirections struct {

	//The list of CompoundSolveSteps that, when applied in order, would cause
	//the SolveDirection's Grid() to be solved.
	CompoundSteps []*CompoundSolveStep
	// contains filtered or unexported fields
}

type SolveStep struct {
	//The technique that was used to identify that this step is logically valid at this point in the solution.
	Technique SolveTechnique
	//The cells that will be affected by the techinque (either the number to fill in or possibilities to exclude).
	TargetCells CellRefSlice
	//The numbers we will remove (or, in the case of Fill, add) to the TargetCells.
	TargetNums IntSlice
	//The cells that together lead the techinque to logically apply in this case; the cells behind the reasoning
	//why the TargetCells will be mutated in the way specified by this SolveStep.
	PointerCells CellRefSlice
	//The specific numbers in PointerCells that lead us to remove TargetNums from TargetCells.
	//This is only very rarely needed (at this time only for hiddenSubset techniques)
	PointerNums IntSlice
	// contains filtered or unexported fields
}

type SolveTechnique interface {
	//Name returns the human-readable shortname of the technique.
	Name() string
	//Description returns a human-readable phrase that describes the logical reasoning applied in the particular step; why
	//it is valid.
	Description(*SolveStep) string

	//Candidates returns all of the SolveSteps that this Technique sees at the
	//current state of Grid. All of the returned steps are valid and useful to
	//apply. Will return early once maxResults have been found if maxResults >
	//0.
	Candidates(grid Grid, maxResults int) []*SolveStep

	//IsFill returns true if the techinque's action when applied to a grid is to fill a number (as opposed to culling possbilitie).
	IsFill() bool

	//Variants returns a slice of strings representing all of the various variantnames
	//that steps produced from this technique could ever have. This is useful as part of
	//enumerating all possible TechniqueVariant names that any steps could ever emit.
	Variants() []string
	// contains filtered or unexported methods
}

type SymmetryType int