A lightweight tool for conducting parameter studies.
Project description
About
Optionset allows users to succinctly set up and conduct parameter studies for applications that reference text-based dictionary files.
Installation
The easiest way to install Optionset is the Python package manager pip
:
$ pip install optionset
Documentation
The program enables and disables user-predefined options in text-based dictionary files in the base directory and below. The user specifies the lines in the files that will either be enabled or disabled by adding macro commands as commented text.
For example, suppose a parameter study involved varying fluid properties and the kinematic viscosity was listed in a dictionary file as,
nu = 1.5e-5; // air [m^2/s]
//nu = 1e-6; // water [m^2/s]
In the above text, the property of air will be read, since the line with water is commented out. To enable water instead, the user could simply switch which lines are commented. However, this task is often inconvenient, especially with many properties listed across multiple files. Alternatively, the following macros can be added to the comments to mark them as a parameters to be varied.
nu = 1.5e-5; // air [m^2/s] ~nu air
//nu = 1e-6; // water [m^2/s] ~nu water
This setup allows the user to easily switch between air and water simulations without manually editing the dictionary file. On the command line, simply run,
$ optionset.py ~nu water
and the dictionary file will be modified and re-written as,
//nu = 1.5e-5; // air [m^2/s] ~nu air
nu = 1e-6; // water [m^2/s] ~nu water
so that water is now the active property. Within the prescribed macros,
~nu
is the ‘option’ while air
and water
are the ‘settings’. An unlimited
number of unique options and settings are allowed. Each can only be composed
of alphanumerical words with dots, pluses, minuses, and underscores, and
the first 1+ characters in the option must be a symbol such as ~@$^&=|?
.
Use optionset.py -a
to view all of the options that you have set, or even
optionset.py -a ~nu
to view all options that begin with ~nu
. Additionally,
optionset.py -a -f
will show all options and their associated files.
To avoid comment clutter, multi-line options are encouraged by writing *
in
front of the first and last options in a series (see text on left),
functions // *~forces on | <--- | functions // ~forces on
{ |INSTEAD| { // ~forces on
#include "forces" | OF | #include "forces"// ~forces on
} // *~forces on | ---> | } // ~forces on
// // ~forces off | | // // ~forces off
An additional feature is the variable option. For variable options the
macro command must be formatted with a Perl-styled regular expression
='<regex>'
that matches the desired text to be changed such as,
variable_option = -5.5; // ~varOption ='= (.*);'
To change variable_option
to 6.7 use, optionset.py ~varOption 6.7
,
and the line within the file becomes,
variable_option = 6.7; // ~varOption ='= (.*);'
To enable Bash tab completion add the following lines to your ~/.bashrc
,
function os {
optionset.py "$@" --bash-completion;
source /home/mcjones/.optionset/bash_completion;
}
and run the program using os
instead of optionset.py
.
Using your favorite scripting language, it is convenient to glue this program
into more advanced option variation routines to create parameter sweeps and
case studies. While this program is generally called from the command line, it
is also possible to directly import this functionality into a Python script:
from optionset import optionset
optionset(['~nu', 'water']) # set kinematic viscosity to that of water
For command line usage, the following arguments are permitted.
positional arguments:
option 'option' name
setting 'setting' for given 'option'
optional arguments:
-h, --help show this help message and exit
-H, --help-full show full help message and exit
-a, --available show available option-setting combinations; allows for
unix-style glob-expression searching; '-a' is implicitely
enabled when no 'setting' is input
-f, --show-files show files associate with available options
-v, --verbose turn on verbose output
-q, --quiet turn off all standard output
-d, --debug turn on debug output in log file
-n, --no-log do not write log file to
'/home/mcjones/.optionset/log.optionset.py'
--bash-completion auto-generate bash tab-completion script
'/home/mcjones/.optionset/bash_completion'
--version show version and exit
License
Optionset is licensed under GNU GPLv3. See the LICENSE document.
See Also
pyexpander: macro-processing with Python
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for optionset-20.9.22-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6998f8c6ec139641f3274b6655655c6e621a5873f0d2369aa0dcdb506ecc6cf0 |
|
MD5 | 51d0f718c87200f16621904775770f2f |
|
BLAKE2b-256 | dfbda5fbcad395cac13adca0220cb2a7574bcfa8c8562394726853bf1b4741a9 |