{"id":22752402,"url":"https://github.com/perrette/runner","last_synced_at":"2025-07-28T20:08:53.768Z","repository":{"id":144978296,"uuid":"189655389","full_name":"perrette/runner","owner":"perrette","description":"Sample parameters, run model ensemble over multiple processors","archived":false,"fork":false,"pushed_at":"2019-06-01T11:21:17.000Z","size":459,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-28T20:03:57.123Z","etag":null,"topics":["ensemble","parameters","sampling","simulations"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perrette.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-31T20:36:19.000Z","updated_at":"2019-11-18T22:55:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"c7d10b94-057b-4e0b-8b4d-aa55ae7d7583","html_url":"https://github.com/perrette/runner","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/perrette/runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perrette%2Frunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perrette%2Frunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perrette%2Frunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perrette%2Frunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perrette","download_url":"https://codeload.github.com/perrette/runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perrette%2Frunner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267578003,"owners_count":24110351,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ensemble","parameters","sampling","simulations"],"created_at":"2024-12-11T05:11:41.176Z","updated_at":"2025-07-28T20:08:53.741Z","avatar_url":"https://github.com/perrette.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# runner\n\nSample parameters, run model ensemble over multiple processors\n\nRequirements\n============\n- python 2.7 and 3\n- numpy (tested with 1.11)\n- scipy (tested with 0.16 and 0.18)\n\nInstall\n=======\n    python setup.py install\n\nUsage\n=====\nUse command-line help:\n\n- [job -h](doc/job.txt)\n- [job product -h](doc/product.txt)\n- [job sample -h](doc/sample.txt)\n- [job resample -h](doc/resample.txt)\n- [job run -h](doc/run.txt)\n- [job analyze -h](doc/analyze.txt)\n\n\nExamples\n========\n\nParameter sampling\n------------------\n\nFactorial combination of parameters:\n\n    job product a=2,3,4 b=0,1\n    \n     a      b\n     2      0\n     2      1\n     3      0\n     3      1\n     4      0\n     4      1\n\nMonte-carlo sampling:\n\n    job sample a=U?0,1 b=N?0,1 --size 10 --seed 4\n\n         a      b\n    0.425298236238 0.988953805595\n    0.904416005793 2.62482283016\n    0.68629932356 0.705445219934\n    0.397627445478 -0.766770633921\n    0.577938292179 -0.522609467132\n    0.0967029839014 -0.14215407458\n    0.71638422414 0.0495725958965\n    0.26977288246 0.519632323554\n    0.197268435996 -1.60068615198\n    0.800898609767 -0.948326628599\n\nThe above command draws 10 samples from \"a\" as uniform distribution between 0 \nand 1 and \"b\" as normal distribution of mean 0 and standard deviation 1. \nThe seed parameter sets the random state, to make the sampling reproducible.\nSampling method defaults to Latin Hypercube Sampling, built on the pyDOE \npackage (copied in runner to reduce external dependencies).\n\n\nRun model ensemble\n------------------\n\nThe canonical form of `job run` is:\n\n    job run [OPTIONS] -- EXECUTABLE [OPTIONS]\n    job run [OPTIONS] -m CUSTOM\n\nwhere `EXECUTABLE` is your model executable or a command, followed by its\narguments, and `CUSTOM` indicates a custom model interface. \nNote the `--` that separates `job run` arguments `OPTIONS` from the\nexecutable.  When there is no ambiguity in the command-line arguments (as seen\nby python's argparse) it may be dropped. `job run` options determine in which\nmanner to run the model, which parameter values to vary (the ensemble), and how\nto communicate these parameter values to the model.  The most straightforward\nway it to use formattable command-line argument. For instance using canonical\nUNIX command `echo` as executable:\n\n    job run -p a=2,3,4 b=0,1 -o out -- echo --a {a} --b {b} --out {}\n\nThe standard output is written in log files under `out/RUNID`:\n\n    cat out/*/log.out\n\n    --a 2 --b 0 --out out/0\n    --a 2 --b 1 --out out/1\n    --a 3 --b 0 --out out/2\n    --a 3 --b 1 --out out/3\n    --a 4 --b 0 --out out/4\n    --a 4 --b 1 --out out/5\n\nThe command above runs an ensemble of 6 model versions, by calling \n`echo --a {a} --b {b} --out {}`  where `{a}`, `{b}` and `{}` \nare formatted using runtime with\nparameter and run directory values, as displayed in the output above.\nParameter ensembles generated by `job sample` can also be provided as input via\n`-i/--params-file` option instead of `-p/--params`. \nThe `job run` parameter `-o/--out-dir` indicates experiment directory, under\nwhich individual ensemble member run directories `{}` will be created. There\nare a number of options to determine how this should be done (e.g.\n`-a/--auto-dir` to create sub-directory based on parameter names and values).\nThe command is executed in the background  and the standard output is\nsaved to log files. \n\nThere are a number of other ways to communicate parameter values to your model\n(see also `--arg-prefix` parameter, e.g. with `--arg-prefix \"--{} \"` to achieve\nthe same result with less redundancy, when parameter names match). Parameters\ncan also be passed via a file:\n\n    job run -p a=2,3,4 b=0,1 -o out --file-name params.txt --file-type linesep --line-sep \" \"\n\n    cat out/*/params.txt\n\n    a 2\n    b 0\n    a 2\n    b 1\n    a 3\n    b 0\n    a 3\n    b 1\n    a 4\n    b 0\n    a 4\n    b 1\n\nwith a number of other file types. File types that involve grouping, such as\nnamelist, require a group prefix with a `.` separator in the parameter name:\n\n    job run -p g1.a=0,1 g2.b=2. -o out --file-name params.txt --file-type namelist\n\n    cat out/*/params.txt\n\n    \u0026g1\n     a               = 0          \n    /\n    \u0026g2\n     b               = 2.0        \n    /\n    \u0026g1\n     a               = 1          \n    /\n    \u0026g2\n     b               = 2.0        \n    /\n\nAdditionally, parameters can be set as environment variables via `--env-prefix`\nargument (e.g. `--env-prefix \"\"` for direct access via `$NAME` within the\nscript).\n\n\nCustom model interface\n----------------------\nFor more complex model setup you may subclass `runner.model.ModelInterface` methods\n`setup` and `postprocess`. See [examples/custom.py](examples/custom.py) how to do that.\n\n\nNote for use on the cluster\n---------------------------\nThe current version makes use of python's multiprocessing.Pool to handle parallel\ntasks. When running on the cluster, it is up to the user to allocate ressources, via\nsbatch, e.g. by simply writing the command in a bash script:\n\n    \n    # write job script\n    echo job run -p a=2,3,4 b=0,1 -o out -- echo --a {a} --b {b} --out {} \u003e jobrun.sh\n\n    # submit with slurm with 10 procs\n    sbatch -n 10 jobrun.sh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperrette%2Frunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperrette%2Frunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperrette%2Frunner/lists"}