Optionset: parameter studies made easy
======================================
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
:code:`pip`:
.. code-block:: bash
$ pip install optionset
To install as a user (no root access required), use
.. code-block:: bash
$ 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,
.. code-block:: cpp
// 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.
.. code-block:: cpp
// 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,
.. code-block:: bash
$ optionset ~nu water
and the dictionary file will be modified and re-written as,
.. code-block:: cpp
// 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,
:code:`~nu` is the 'option' while :code:`air` and :code:`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
:code:`~@$^&=|?`. Recognizable comments are denoted by :code:`//` :code:`#`
:code:`%` :code:`!` or :code:`--`.
Use :code:`optionset -a` to view all of the options that you have set, or
even :code:`optionset -a ~nu` to view all options that begin with
:code:`~nu`. Additionally, :code:`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
:code:`*` in front of the first and last options in a series. For example,
suppose a dictionary file specified a series of functions to run.
.. code-block:: cpp
// 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,
.. code-block:: cpp
// Inside notional dictionary file
// // ~functions off
functions // *~functions on
{
#include "cuttingPlane"
#include "streamLines"
} // *~functions on
And running :code:`optionset ~functions off` would result in the following
modifications to the file, thereby disabling the functions.
.. code-block:: cpp
// 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
:code:`='<regex>'` that matches the desired text to be changed with parentheses
:code:`()`, for example,
.. code-block:: cpp
// Inside notional dictionary file
rho 1.225; // ~density ='rho (.*);'
Here, :code:`(.*)` matches `1.225` in :code:`rho 1.225;`. To change this to
`1025`, run :code:`optionset ~density 1025`, and the line within the
file now becomes,
.. code-block:: cpp
// 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 :code:`optionset -a`. To narrow the search to options that start with
:code:`~nu`, run :code:`optionset -a ~nu`. Additionally, :code:`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 :code:`optionset -a`.
.. code-block:: bash
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
:code:`~/.bashrc`,
.. code-block:: bash
# Inside ~/.bashrc
function os {
optionset "$@" --bash-completion;
source $HOME/.optionset/bash_completion;
}
and run the program using :code:`os` instead of :code:`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.
.. code-block:: python
# 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.
.. code-block:: bash
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,
.. code-block:: bash
$ optionset -h
License
-------
Optionset is licensed under GNU GPLv3. See the LICENSE document.
See Also
--------
* `Github repository`_: for latest source code, unit tests, and examples.
* `pyexpander`_: macro-processing with Python.
.. _Github repository: https://github.com/MattCJones/optionset
.. _pyexpander: https://pypi.org/project/pyexpander/
Raw data
{
"_id": null,
"home_page": "https://github.com/MattCJones/optionset",
"name": "optionset",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "utility, macro-processor",
"author": "Matthew C. Jones",
"author_email": "matt.c.jones.aoe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/69/263e733306ae95e6578315f929fec8e47745fff499747367a5ef1a7c0e7f/optionset-25.1.3.tar.gz",
"platform": null,
"description": "Optionset: parameter studies made easy\n======================================\n\nAbout Optionset\n---------------\n\nOptionset allows users to succinctly set up and conduct parameter studies for\napplications that reference text-based dictionary files.\n\nAuthor\n------\n\nMatthew C. Jones matt.c.jones.aoe@gmail.com\n\nInstallation\n------------\n\nThe easiest way to install Optionset is with the Python package manager\n:code:`pip`:\n\n.. code-block:: bash\n\n $ pip install optionset\n\nTo install as a user (no root access required), use\n\n.. code-block:: bash\n\n $ pip install --user optionset\n\n\nDocumentation\n-------------\n\nBasic Usage\n^^^^^^^^^^^\n\nOptionset enables and disables user-predefined options in text-based\ndictionary files in the base directory and below. The user specifies the lines\nin the files that will either be enabled or disabled by adding macro commands\nas commented text.\n\nFor example, suppose a parameter study involved varying fluid properties and\nthe kinematic viscosity was listed in a dictionary file as,\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n nu 1.5e-5; // viscosity of air in units of [m^2/s]\n //nu 1e-6; // viscosity of water in units of [m^2/s]\n\nIn the above text, the property of water will be ignored, since the second line\nis commented out. To enable water instead of air, the user could simply switch\nwhich line is commented. However, this task is often inconvenient, especially\nwith numerous variable properties listed across multiple files. Alternatively,\nthe following macro instructions can be added to the commented part of the text\nto mark them as a parameters to be varied.\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n nu 1.5e-5; // viscosity of air in units of [m^2/s] ~nu air\n //nu 1e-6; // viscosity of water in units of [m^2/s] ~nu water\n\nThis setup allows the user to easily switch between air and water simulations\nwithout manually editing the dictionary file. On the command line, simply run,\n\n.. code-block:: bash\n\n $ optionset ~nu water\n\nand the dictionary file will be modified and re-written as,\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n //nu 1.5e-5; // viscosity of air in units of [m^2/s] ~nu air\n nu 1e-6; // viscosity of water in units of [m^2/s] ~nu water\n\nso that water is now the active property. Within the prescribed macros,\n:code:`~nu` is the 'option' while :code:`air` and :code:`water` are the\n'settings'. An unlimited number of arbitrary options and settings are allowed.\nEach must be composed of alphanumerical words with dots, pluses, minuses, and\nunderscores, and the first 1+ characters in the option must be a symbol such as\n:code:`~@$^&=|?`. Recognizable comments are denoted by :code:`//` :code:`#`\n:code:`%` :code:`!` or :code:`--`.\n\nUse :code:`optionset -a` to view all of the options that you have set, or\neven :code:`optionset -a ~nu` to view all options that begin with\n:code:`~nu`. Additionally, :code:`optionset -a -f` will show all options and\ntheir associated files.\n\nMulti-line Options\n^^^^^^^^^^^^^^^^^^\n\nTo avoid comment clutter, multi-line options are encouraged by annotating\n:code:`*` in front of the first and last options in a series. For example,\nsuppose a dictionary file specified a series of functions to run.\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n // // ~functions off\n functions // ~functions on\n { // ~functions on\n #include \"cuttingPlane\" // ~functions on\n #include \"streamLines\" // ~functions on\n } // ~functions on\n\nThe five repeated macros could instead be written more succinctly as,\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n // // ~functions off\n functions // *~functions on\n {\n #include \"cuttingPlane\"\n #include \"streamLines\"\n } // *~functions on\n\nAnd running :code:`optionset ~functions off` would result in the following\nmodifications to the file, thereby disabling the functions.\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n // ~functions off\n //functions // *~functions on\n //{\n // #include \"cuttingPlane\"\n // #include \"streamLines\"\n //} // *~functions on\n\nVariable Options\n^^^^^^^^^^^^^^^^\n\nAn additional feature is the variable option. For variable options the macro\ncommand must be formatted with a Perl-styled regular expression\n:code:`='<regex>'` that matches the desired text to be changed with parentheses\n:code:`()`, for example,\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n rho 1.225; // ~density ='rho (.*);'\n\nHere, :code:`(.*)` matches `1.225` in :code:`rho 1.225;`. To change this to\n`1025`, run :code:`optionset ~density 1025`, and the line within the\nfile now becomes,\n\n.. code-block:: cpp\n\n // Inside notional dictionary file\n rho 1025; // ~density ='rho (.*);'\n\nViewing Available Options and Settings\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nTo view all of the available options and settings that have been prescribed,\nrun :code:`optionset -a`. To narrow the search to options that start with\n:code:`~nu`, run :code:`optionset -a ~nu`. Additionally, :code:`optionset\n-a -f` will list all associated file locations.\n\nImplementing the option/setting macros in the above examples, the following\noutput is generated from running :code:`optionset -a`.\n\n.. code-block:: bash\n\n Showing available options and settings matching '*'\n (' inactive ', '> active <', '? both ?', '= variable =')\n ~functions\n > off <\n on\n ~nu\n air\n > water <\n ~density\n = 1025 =\n\nBash Tab Completion\n^^^^^^^^^^^^^^^^^^^\n\nTo enable Bash shell tab completion, add the following to your\n:code:`~/.bashrc`,\n\n.. code-block:: bash\n\n # Inside ~/.bashrc\n function os {\n optionset \"$@\" --bash-completion;\n source $HOME/.optionset/bash_completion;\n }\n\nand run the program using :code:`os` instead of :code:`optionset`.\n\nScripting\n^^^^^^^^^\n\nUsing your favorite scripting language, it is convenient to glue this program\ninto more advanced option variation routines to create parameter sweeps and\ncase studies. While this program is generally called as a shell command, it\nis also possible to directly import this functionality into a Python script.\n\n.. code-block:: python\n\n # Inside notional Python script\n from optionset import optionset\n optionset(['~nu', 'water']) # set kinematic viscosity to that of water\n\nCommand-Line Arguments\n^^^^^^^^^^^^^^^^^^^^^^\n\nFor command line usage, the following arguments are permitted.\n\n.. code-block:: bash\n\n positional arguments:\n option 'option' name\n setting 'setting' for given 'option'\n\n optional arguments:\n -h, --help show this help message and exit\n -H, --help-full show full help message and exit\n -a, --available show available option-setting combinations; allows for\n unix-style glob-expression searching; '-a' is implicitely\n enabled when no 'setting' is input\n -f, --show-files show files associate with available options\n -v, --verbose turn on verbose output\n -q, --quiet turn off all standard output\n -d, --debug turn on debug output in log file\n -n, --no-log do not write log file to\n '$HOME/.optionset/log_optionset'\n --rename-option rename input option in all files\n --rename-setting rename input setting in all files\n --bash-completion auto-generate bash tab-completion script\n '$HOME/.optionset/bash_completion'\n --version show version and exit\n\nTo view help from the terminal, run,\n\n.. code-block:: bash\n\n $ optionset -h\n\nLicense\n-------\n\nOptionset is licensed under GNU GPLv3. See the LICENSE document.\n\nSee Also\n--------\n\n* `Github repository`_: for latest source code, unit tests, and examples.\n* `pyexpander`_: macro-processing with Python.\n\n.. _Github repository: https://github.com/MattCJones/optionset\n.. _pyexpander: https://pypi.org/project/pyexpander/\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A lightweight tool for conducting parameter studies.",
"version": "25.1.3",
"project_urls": {
"Homepage": "https://github.com/MattCJones/optionset"
},
"split_keywords": [
"utility",
" macro-processor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "994b73d0225b718b7548f0e1ceef7a7374779c7795e461dce61776d5f944c662",
"md5": "e8f012a49d4846bc160f34048ba44e93",
"sha256": "96b1552cec10102cb158b53fa6b3e49069f2fc753f7b52d89b331b740a139fdf"
},
"downloads": -1,
"filename": "optionset-25.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8f012a49d4846bc160f34048ba44e93",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 38482,
"upload_time": "2025-01-03T21:55:28",
"upload_time_iso_8601": "2025-01-03T21:55:28.240873Z",
"url": "https://files.pythonhosted.org/packages/99/4b/73d0225b718b7548f0e1ceef7a7374779c7795e461dce61776d5f944c662/optionset-25.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0669263e733306ae95e6578315f929fec8e47745fff499747367a5ef1a7c0e7f",
"md5": "ec54aa9ae908a04bcb24ec21a42754ae",
"sha256": "45ac1de736b83b2e09e74bb353ba96565a4b5fe89965bbae7e73bc118dc2bd93"
},
"downloads": -1,
"filename": "optionset-25.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ec54aa9ae908a04bcb24ec21a42754ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 38957,
"upload_time": "2025-01-03T21:55:29",
"upload_time_iso_8601": "2025-01-03T21:55:29.510158Z",
"url": "https://files.pythonhosted.org/packages/06/69/263e733306ae95e6578315f929fec8e47745fff499747367a5ef1a7c0e7f/optionset-25.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 21:55:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MattCJones",
"github_project": "optionset",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "optionset"
}
JSON
