Skip to main content

A lightweight tool for conducting parameter studies.

Project description

About Optionset

Optionset allows users to succinctly set up and conduct parameter studies for applications that reference text-based dictionary files.

Author

Matthew C. Jones matt.c.jones.aoe@gmail.com

Installation

The easiest way to install Optionset is with the Python package manager pip:

$ pip install optionset

To install as a user (no root access required), use

$ pip install --user optionset

Documentation

Basic Usage

Optionset 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,

// Inside notional dictionary file
nu    1.5e-5; // viscosity of air in units of [m^2/s]
//nu    1e-6; // viscosity of water in units of [m^2/s]

In the above text, the property of water will be ignored, since the second line is commented out. To enable water instead of air, the user could simply switch which line is commented. However, this task is often inconvenient, especially with numerous variable properties listed across multiple files. Alternatively, the following macro instructions can be added to the commented part of the text to mark them as a parameters to be varied.

// Inside notional dictionary file
nu    1.5e-5; // viscosity of air in units of [m^2/s] ~nu air
//nu    1e-6; // viscosity of water in units of [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 ~nu water

and the dictionary file will be modified and re-written as,

// Inside notional dictionary file
//nu    1.5e-5; // viscosity of air in units of [m^2/s] ~nu air
nu    1e-6; // viscosity of water in units of [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 arbitrary options and settings are allowed. Each must 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 ~@$^&=|?. Recognizable comments are denoted by // # % ! or --.

Use optionset -a to view all of the options that you have set, or even optionset -a ~nu to view all options that begin with ~nu. Additionally, optionset -a -f will show all options and their associated files.

Multi-line Options

To avoid comment clutter, multi-line options are encouraged by annotating * in front of the first and last options in a series. For example, suppose a dictionary file specified a series of functions to run.

// Inside notional dictionary file
// // ~functions off
functions                   // ~functions on
{                           // ~functions on
    #include "cuttingPlane" // ~functions on
    #include "streamLines"  // ~functions on
}                           // ~functions on

The five repeated macros could instead be written more succinctly as,

// Inside notional dictionary file
// // ~functions off
functions                   // *~functions on
{
    #include "cuttingPlane"
    #include "streamLines"
}                           // *~functions on

And running optionset ~functions off would result in the following modifications to the file, thereby disabling the functions.

// Inside notional dictionary file
 // ~functions off
//functions                   // *~functions on
//{
//    #include "cuttingPlane"
//    #include "streamLines"
//}                           // *~functions on

Variable Options

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 with parentheses (), for example,

// Inside notional dictionary file
rho   1.225; // ~density ='rho   (.*);'

Here, (.*) matches 1.225 in rho 1.225;. To change this to 1025, run optionset ~density 1025, and the line within the file now becomes,

// Inside notional dictionary file
rho   1025; // ~density ='rho   (.*);'

Viewing Available Options and Settings

To view all of the available options and settings that have been prescribed, run optionset -a. To narrow the search to options that start with ~nu, run optionset -a ~nu. Additionally, optionset -a -f will list all associated file locations.

Implementing the option/setting macros in the above examples, the following output is generated from running optionset -a.

Showing available options and settings matching '*'
('  inactive  ', '> active <', '? both ?', '= variable =')
  ~functions
        > off <
          on
  ~nu
          air
        > water <
  ~density
        = 1025 =

Bash Tab Completion

To enable Bash shell tab completion, add the following to your ~/.bashrc,

# Inside ~/.bashrc
function os {
    optionset "$@" --bash-completion;
    source $HOME/.optionset/bash_completion;
}

and run the program using os instead of optionset.

Scripting

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 as a shell command, it is also possible to directly import this functionality into a Python script.

# Inside notional Python script
from optionset import optionset
optionset(['~nu', 'water'])  # set kinematic viscosity to that of water

Command-Line Arguments

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/.optionset/log_optionset'
  --rename-option    rename input option in all files
  --rename-setting   rename input setting in all files
  --bash-completion  auto-generate bash tab-completion script
                      '$HOME/.optionset/bash_completion'
  --version          show version and exit

To view help from the terminal, run,

$ optionset -h

License

Optionset is licensed under GNU GPLv3. See the LICENSE document.

See Also

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

optionset-25.1.3.tar.gz (39.0 kB view details)

Uploaded Source

Built Distribution

optionset-25.1.3-py3-none-any.whl (38.5 kB view details)

Uploaded Python 3

File details

Details for the file optionset-25.1.3.tar.gz.

File metadata

  • Download URL: optionset-25.1.3.tar.gz
  • Upload date:
  • Size: 39.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.5

File hashes

Hashes for optionset-25.1.3.tar.gz
Algorithm Hash digest
SHA256 45ac1de736b83b2e09e74bb353ba96565a4b5fe89965bbae7e73bc118dc2bd93
MD5 ec54aa9ae908a04bcb24ec21a42754ae
BLAKE2b-256 0669263e733306ae95e6578315f929fec8e47745fff499747367a5ef1a7c0e7f

See more details on using hashes here.

File details

Details for the file optionset-25.1.3-py3-none-any.whl.

File metadata

  • Download URL: optionset-25.1.3-py3-none-any.whl
  • Upload date:
  • Size: 38.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.5

File hashes

Hashes for optionset-25.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 96b1552cec10102cb158b53fa6b3e49069f2fc753f7b52d89b331b740a139fdf
MD5 e8f012a49d4846bc160f34048ba44e93
BLAKE2b-256 994b73d0225b718b7548f0e1ceef7a7374779c7795e461dce61776d5f944c662

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page