{"id":17614205,"url":"https://github.com/technologicat/sudoku_lhs","last_synced_at":"2025-04-30T22:08:32.872Z","repository":{"id":57472171,"uuid":"89483697","full_name":"Technologicat/sudoku_lhs","owner":"Technologicat","description":"Latin hypercube sampler with sudoku constraint","archived":false,"fork":false,"pushed_at":"2017-04-26T13:40:50.000Z","size":27,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-30T22:08:17.436Z","etag":null,"topics":["latin-hypercube","numerical","numpy","python","python2","python27","python3","python34","sampling-methods","sudoku"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Technologicat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-26T13:26:36.000Z","updated_at":"2024-02-26T17:00:19.000Z","dependencies_parsed_at":"2022-08-30T15:20:23.386Z","dependency_job_id":null,"html_url":"https://github.com/Technologicat/sudoku_lhs","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fsudoku_lhs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fsudoku_lhs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fsudoku_lhs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Technologicat%2Fsudoku_lhs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Technologicat","download_url":"https://codeload.github.com/Technologicat/sudoku_lhs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251789612,"owners_count":21644085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["latin-hypercube","numerical","numpy","python","python2","python27","python3","python34","sampling-methods","sudoku"],"created_at":"2024-10-22T18:32:52.802Z","updated_at":"2025-04-30T22:08:32.835Z","avatar_url":"https://github.com/Technologicat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## sudoku_lhs\n\nLatin hypercube sampler with a sudoku-like constraint\n![Example of a sudoku sample](example.png)\n\n### Introduction\n\nThe sudoku LHS algorithm is a bit like the first stage in the design of an `N`-dimensional sudoku puzzle, hence the name: each \"sudoku box\" must have exactly the same number of samples, and no two samples may occur on the same axis-aligned hyperplane.\n\nSudoku LHS runs in linear time (w.r.t. the number of samples), and requires a linear amount of memory. Details are provided in the [source code comments](sudoku_lhs/sudoku.py).\n\nSudoku LHS  is inspired by, but not related to, orthogonal sampling. The latter refers to LHS sampling using orthogonal arrays; about that, see the articles:\n  - B. Tang 1993:    Orthogonal Array-Based Latin Hypercubes,\n  - A. B. Owen 1992: Orthogonal arrays for computer experiments, integration and visualization,\n  - K. Q. Ye 1998:   Orthogonal column Latin hypercubes and their application in computer experiments\n\nLatin hypercube sampling itself was first described in\n  - M. D. McKay, R. J. Beckman, W. J. Conover, 1979. A Comparison of Three Methods for Selecting Values of Input Variables in the Analysis of Output from a Computer Code\n\nFor a quick description of classical LHS, see e.g. [Wikipedia](http://en.wikipedia.org/wiki/Latin_hypercube_sampling).\n\n### Comparison to other methods\n\n#### Stratification\n\nSudoku LHS improves on pure Monte Carlo and classical LHS, but loses to [IHS](http://people.sc.fsu.edu/~jburkardt/cpp_src/ihs/ihs.html), on which the original paper is:\n  - Beachkofski, B. K. and Grandhi, R. V., 2002. Improved distributed hypercube sampling. In 43rd AIAA structures, structural dynamics, and materials conference. AIAA-2002-1274. Denver, CO.\n\nIHS is (close to?) ideal in this regard, as it specifically aims to maximize the distance between pairs of sampled points.\n\n#### Statistical independence of sample components\n\nIn the sense of the pairwise linear correlation coefficient of columns (which contain the permutations), sudoku LHS typically improves statistical independence when compared to pure Monte Carlo or classical LHS. The improvement is the most marked in two dimensions (because sudoku LHS stratifies in 1 and `N` dimensions, and here `N` = 2), but some improvement is also noticeable for at least `N` = 3 and `N` = 4 (where stratification occurs only in 1 and 3 (resp. 1 and 4) dimensions). See [test/sudoku_cor_test.py](test/sudoku_cor_test.py) to produce actual numbers.\n\nOrthogonal sampling, by definition, produces the ideal sample in this regard (exactly zero correlation).\n\n\n### Example\n\n```python\nimport sudoku_lhs\n# input: dimensions, sudoku boxes per axis, number of samples to place in each sudoku box\n# output: sample array, number of bins per axis\nS,m = sudoku_lhs.sudoku.sample(2, 3, 1, visualize=True, verbose=True)\n```\n\nTrivial combinatorial and classical LHS samplers are also provided for comparison:\n\n```python\nS2 = sudoku_lhs.lhs.sample(2, m)  # same number of bins as above\nS3 = sudoku_lhs.comb.sample(2, m)\n```\n\nNote that combinatorial sampling is very expensive (generates a very large number of samples), which is why LHS methods have been developed.\n\n\n### Installation\n\n#### From PyPI\n\nInstall as user:\n\n```bash\npip install sudoku-lhs --user\n```\n\nInstall as admin:\n\n```bash\nsudo pip install sudoku-lhs\n```\n\n#### From GitHub\n\nAs user:\n\n```bash\ngit clone https://github.com/Technologicat/sudoku_lhs.git\ncd sudoku_lhs\npython setup.py install --user\n```\n\nAs admin, change the last command to\n\n```bash\nsudo python setup.py install\n```\n\n\n### Historical note\n\nThe variant of sudoku sampling implemented here was originally developed as part of the SAVU project in 2010, and briefly mentioned in the author's paper\n  - Jeronen, J. SAVU: A Statistical Approach for Uncertain Data in Dynamics of Axially Moving Materials. In: A. Cangiani, R. Davidchack, E. Georgoulis, A. Gorban, J. Levesley, M. Tretyakov (eds.) Numerical Mathematics and Advanced Applications 2011: Proceedings of ENUMATH 2011, the 9th European Conference on Numerical Mathematics and Advanced Applications, Leicester, September 2011, 831-839, Springer, 2013.\n\nLater, Shields and Zhang independently developed and published a variant of sudoku sampling, published in\n  - Michael D. Shields and Jiaxin Zhang. The generalization of Latin hypercube sampling. Reliability Engineering \u0026 System Safety 148:96-108, 2016. [doi:10.1016/j.ress.2015.12.002](http://doi.org/10.1016/j.ress.2015.12.002)\n\n\n### License\n\n[BSD](LICENSE.md). Copyright 2010-2017 Juha Jeronen and University of Jyväskylä.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnologicat%2Fsudoku_lhs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnologicat%2Fsudoku_lhs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnologicat%2Fsudoku_lhs/lists"}