================= Command Reference ================= This is a reference for all commands in the Ramble command line interface. The same information is available through :ref:`ramble-help`. ==================== ==================================================================== Category Commands ==================== ==================================================================== Application dev | :ref:`edit ` Query applications | :ref:`info `, :ref:`list ` Cleanup | :ref:`clean ` Configuration | :ref:`config `, :ref:`mirror `, :ref:`repo ` Data | :ref:`data ` Developer | :ref:`attributes `, :ref:`commands `, :ref:`debug `, :ref:`license `, :ref:`python `, :ref:`software-definitions `, :ref:`style `, :ref:`unit-test ` More help | :ref:`docs `, :ref:`help ` Results | :ref:`results ` Workspaces | :ref:`deployment `, :ref:`on `, :ref:`workspace ` ==================== ==================================================================== ---- .. _ramble: ramble ------ A flexible benchmark experiment manager. .. code-block:: console ramble [-hHdNASPklLmpvV] [--color {always,never,auto}] [-c CONFIG_VARS] [-C DIR] [--disable-passthrough] [--timestamp] [--pdb] [-w WRKSPC | -D DIR | -W] [--use-workspace-repo] [--resolve-variables-in-subprocesses] [--overwrite-inventories] [--mock-applications] [--mock-modifiers] [--mock-package-managers] [--mock-workflow-managers] [--mock-systems] [--mock-platforms] [--mock-base-classes] [--mock-base-applications] [--mock-base-modifiers] [--mock-base-package-managers] [--mock-base-workflow-managers] [--mock-base-systems] [--mock-base-platforms] [--sorted-profile STAT] [--lines LINES] [--profile-restrictions PROFILE_RESTRICTIONS] [--stacktrace] COMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit ``-H, --all-help`` show help for all commands (same as ramble help --all) ``--color {always,never,auto}`` when to colorize output (default: auto) ``-c CONFIG_VARS, --config CONFIG_VARS`` add one or more custom, one off config settings. ``-C DIR, --config-scope DIR`` add a custom configuration scope ``-d, --debug`` write out debug messages (more d's for more verbosity: -d, -dd, -ddd, etc.) ``--disable-passthrough`` disable passthrough of expansion variables for debugging ``-N, --disable-logger`` disable the ramble logger. All output will be printed to stdout. ``-A, --aggregate-warnings`` aggregate warnings from the ramble logger to the end of execution. May lose context information ``-S, --suppress-warnings`` suppress warnings from the ramble logger. ``-P, --disable-progress-bar`` disable the progress bars while setting up experiments. ``--timestamp`` Add a timestamp to tty output ``--pdb`` run ramble under the pdb debugger ``-w WRKSPC, --workspace WRKSPC`` run with a specific workspace (see ramble workspace) ``-D DIR, --workspace-dir DIR`` run with a workspace directory (ignore named workspaces) ``-W, --no-workspace`` run without any workspaces activated (see ramble workspace) ``--use-workspace-repo`` when running in a workspace, use its application repository ``--resolve-variables-in-subprocesses`` Allow resolution of environment variables when launching subprocesses ``-k, --insecure`` do not check ssl certificates when downloading ``-l, --enable-locks`` use filesystem locking (default) ``-L, --disable-locks`` do not use filesystem locking (unsafe) ``-m, --mock`` use the builtin.mock repository instead of builtin ``--overwrite-inventories`` enables all workspace actions to overwrite experiment inventories ``--mock-applications`` use mock applications instead of real ones ``--mock-modifiers`` use mock modifiers instead of real ones ``--mock-package-managers`` use mock package managers instead of real ones ``--mock-workflow-managers`` use mock workflow managers instead of real ones ``--mock-systems`` use mock systems instead of real ones ``--mock-platforms`` use mock platforms instead of real ones ``--mock-base-classes`` use mock base classes instead of real ones ``--mock-base-applications`` use mock base applications instead of real ones ``--mock-base-modifiers`` use mock base modifiers instead of real ones ``--mock-base-package-managers`` use mock base package managers instead of real ones ``--mock-base-workflow-managers`` use mock base workflow managers instead of real ones ``--mock-base-systems`` use mock base systems instead of real ones ``--mock-base-platforms`` use mock base platforms instead of real ones ``-p, --profile`` profile execution using cProfile ``--sorted-profile STAT`` profile and sort by one or more of: [calls, ncalls, cumtime, cumulative, filename, line, module] ``--lines LINES`` lines of profile output or 'all' (default: 20) ``--profile-restrictions PROFILE_RESTRICTIONS`` Comma-separated restrictions applied to the cProfiler. When specified, it takes precedence over `--lines`. Example: `--profile-restrictions 'logger,5'` limits the list to functions with 'logger' in the path, and then shows the first 5 of them. See https://docs.python.org/3/library/profile.html#pstats.Stats.print_stats for more details. ``-v, --verbose`` print additional output during builds ``--stacktrace`` add stacktraces to all printed statements ``-V, --version`` show version number and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`attributes ` * :ref:`clean ` * :ref:`commands ` * :ref:`config ` * :ref:`data ` * :ref:`debug ` * :ref:`deployment ` * :ref:`docs ` * :ref:`edit ` * :ref:`help ` * :ref:`info ` * :ref:`license ` * :ref:`list ` * :ref:`mirror ` * :ref:`on ` * :ref:`python ` * :ref:`repo ` * :ref:`results ` * :ref:`software-definitions ` * :ref:`style ` * :ref:`unit-test ` * :ref:`workspace ` ---- .. _ramble-attributes: ramble attributes ----------------- get information about object attributes .. code-block:: console ramble attributes [-ha] [--defined | --undefined] [--by-attribute] [--applications | --modifiers | --package_managers | --workflow_managers | --systems | --platforms | --base_classes | --base_applications | --base_modifiers | --base_package_managers | --base_workflow_managers | --base_systems | --base_platforms] [--maintainers | --tags] ... **Positional arguments** object_or_attr names of objects or attributes to get info for **Optional arguments** ``-h, --help`` show this help message and exit ``--defined`` show names of objects with attributes ``--undefined`` show names of objects without attributes ``-a, --all`` show attributes for all objects ``--by-attribute`` show objects for attributes instead of attributes for objects ``--applications`` show attributes for applications (default) ``--modifiers`` show attributes for modifiers ``--package_managers`` show attributes for package_managers ``--workflow_managers`` show attributes for workflow_managers ``--systems`` show attributes for systems ``--platforms`` show attributes for platforms ``--base_classes`` show attributes for base_classes ``--base_applications`` show attributes for base_applications ``--base_modifiers`` show attributes for base_modifiers ``--base_package_managers`` show attributes for base_package_managers ``--base_workflow_managers`` show attributes for base_workflow_managers ``--base_systems`` show attributes for base_systems ``--base_platforms`` show attributes for base_platforms ``--maintainers`` use maintainers as the attribute. (default) ``--tags`` use tags as the attribute. ---- .. _ramble-clean: ramble clean ------------ remove temporary files and/or downloaded archives .. code-block:: console ramble clean [-hdmpra] **Optional arguments** ``-h, --help`` show this help message and exit ``-d, --downloads`` remove cached downloads (default) ``-m, --misc-cache`` remove long-lived caches ``-p, --python-cache`` remove .pyc, .pyo files and __pycache__ folders ``-r, --reports`` remove pdf and image files generated by ramble reports ``-a, --all`` equivalent to -dmp ---- .. _ramble-commands: ramble commands --------------- list available ramble commands .. code-block:: console ramble commands [-ha] [--update-completion] [--format {subcommands,rst,names,bash}] [--header FILE] [--update FILE] ... **Positional arguments** rst_files list of rst files to search for `_cmd-ramble-` cross-refs **Optional arguments** ``-h, --help`` show this help message and exit ``--update-completion`` regenerate ramble's tab completion scripts ``-a, --aliases`` include command aliases ``--format {subcommands,rst,names,bash}`` format to be used to print the output (default: names) ``--header FILE`` prepend contents of FILE to the output (useful for rst format) ``--update FILE`` write output to the specified file, if any command is newer ---- .. _ramble-config: ramble config ------------- get and set configuration options .. code-block:: console ramble config [-h] [--scope {defaults,system,site,user}] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to read/modify **Subcommands** .. hlist:: :columns: 4 * :ref:`config get ` * :ref:`config blame ` * :ref:`config edit ` * :ref:`config list ` * :ref:`config add ` * :ref:`config remove ` * :ref:`config update ` * :ref:`config revert ` ---- .. _ramble-config-get: ramble config get ^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config get [-h] [section] **Positional arguments** section configuration section to print. options: formatted_executables, config, env_vars, internals, licenses, mirrors, modifiers, software, success_criteria, tables, applications, variables, variants, zips, repos, modifier_repos, package_manager_repos, system_repos, platform_repos, workflow_manager_repos, base_application_repos, base_class_repos, base_modifier_repos, base_package_manager_repos, base_workflow_manager_repos, base_system_repos, base_platform_repos **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-config-blame: ramble config blame ^^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config blame [-h] section **Positional arguments** section configuration section to print. options: formatted_executables, config, env_vars, internals, licenses, mirrors, modifiers, software, success_criteria, tables, applications, variables, variants, zips, repos, modifier_repos, package_manager_repos, system_repos, platform_repos, workflow_manager_repos, base_application_repos, base_class_repos, base_modifier_repos, base_package_manager_repos, base_workflow_manager_repos, base_system_repos, base_platform_repos **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-config-edit: ramble config edit ^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config edit [-h] [--print-file] [section] **Positional arguments** section configuration section to edit. options: formatted_executables, config, env_vars, internals, licenses, mirrors, modifiers, software, success_criteria, tables, applications, variables, variants, zips, repos, modifier_repos, package_manager_repos, system_repos, platform_repos, workflow_manager_repos, base_application_repos, base_class_repos, base_modifier_repos, base_package_manager_repos, base_workflow_manager_repos, base_system_repos, base_platform_repos **Optional arguments** ``-h, --help`` show this help message and exit ``--print-file`` print the file name that would be edited ---- .. _ramble-config-list: ramble config list ^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config list [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-config-add: ramble config add ^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config add [-h] [-f FILE] [path] **Positional arguments** path colon-separated path to config that should be added, e.g. 'config:default:true' **Optional arguments** ``-h, --help`` show this help message and exit ``-f FILE, --file FILE`` file from which to set all config values ---- .. _ramble-config-remove: ramble config remove ^^^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config remove [-h] path **Positional arguments** path colon-separated path to config that should be removed, e.g. 'config:default:true' **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-config-update: ramble config update ^^^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config update [-hy] section **Positional arguments** section section to update **Optional arguments** ``-h, --help`` show this help message and exit ``-y, --yes-to-all`` assume "yes" is the answer to every confirmation request ---- .. _ramble-config-revert: ramble config revert ^^^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble config revert [-hy] section **Positional arguments** section section to update **Optional arguments** ``-h, --help`` show this help message and exit ``-y, --yes-to-all`` assume "yes" is the answer to every confirmation request ---- .. _ramble-data: ramble data ----------- manage data and databases .. code-block:: console ramble data [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`data create-db ` ---- .. _ramble-data-create-db: ramble data create-db ^^^^^^^^^^^^^^^^^^^^^ create the database .. code-block:: console ramble data create-db [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-debug: ramble debug ------------ debugging commands for troubleshooting Ramble .. code-block:: console ramble debug [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`debug report ` ---- .. _ramble-debug-report: ramble debug report ^^^^^^^^^^^^^^^^^^^ .. code-block:: console ramble debug report [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-deployment: ramble deployment ----------------- manage workspace deployments .. code-block:: console ramble deployment [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`deployment push ` * :ref:`deployment pull ` ---- .. _ramble-deployment-push: ramble deployment push ^^^^^^^^^^^^^^^^^^^^^^ Push a workspace deployment .. code-block:: console ramble deployment push [-h] [--tar-archive] [--deployment-name DEPLOYMENT_NAME] [--upload-url UPLOAD_URL] [--phases PHASES [PHASES ...]] [--include-phase-dependencies] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] **Optional arguments** ``-h, --help`` show this help message and exit ``--tar-archive, -t`` create a tar.gz of the deployment directory. ``--deployment-name DEPLOYMENT_NAME, -d DEPLOYMENT_NAME`` Name for deployment. Uses workspace name if not set. ``--upload-url UPLOAD_URL, -u UPLOAD_URL`` URL to upload deployment into. Upload tar if `-t` is specified.. ``--phases PHASES [PHASES ...]`` select phases to execute when performing setup. Phase names support globbing ``--include-phase-dependencies`` if set, phase dependencies are automatically added to the list of executed phases ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ---- .. _ramble-deployment-pull: ramble deployment pull ^^^^^^^^^^^^^^^^^^^^^^ Pull a workspace deployment into current workspace .. code-block:: console ramble deployment pull [-h] --deployment-path DEPLOYMENT_PATH **Optional arguments** ``-h, --help`` show this help message and exit ``--deployment-path DEPLOYMENT_PATH, -p DEPLOYMENT_PATH, -u DEPLOYMENT_PATH`` Path to deployment that should be pulled ---- .. _ramble-docs: ramble docs ----------- open Ramble documentation in a web browser .. code-block:: console ramble docs [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-edit: ramble edit ----------- open application files in $EDITOR .. code-block:: console ramble edit [-h] [--type TYPE] [-c | -d | -t | -m | -r REPO | -N NAMESPACE] [object_name] **Positional arguments** object_name object name **Optional arguments** ``-h, --help`` show this help message and exit ``--type TYPE`` Type of object to edit. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms ``-c, --command`` edit the command with the supplied name ``-d, --docs`` edit the docs with the supplied name ``-t, --test`` edit the test with the supplied name ``-m, --module`` edit the main ramble module with the supplied name ``-r REPO, --repo REPO`` path to repo to edit object in ``-N NAMESPACE, --namespace NAMESPACE`` namespace of object to edit ---- .. _ramble-help: ramble help ----------- get help on ramble and its commands .. code-block:: console ramble help [-ha] [--spec help_command] **Positional arguments** help_command command to get help on **Optional arguments** ``-h, --help`` show this help message and exit ``-a, --all`` list all available commands and options ``--spec`` help on the package specification syntax ---- .. _ramble-info: ramble info ----------- get detailed information on a particular object .. code-block:: console ramble info [-h] [--type TYPE] [--format FORMAT] [--pattern PATTERN] [--overview | --verbose] [--all | --attributes ATTRIBUTES] object **Positional arguments** object Name of object to print info for **Optional arguments** ``-h, --help`` show this help message and exit ``--type TYPE`` type of objects. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms ``--format FORMAT`` list of output format to write. Available options are ['text', 'lists'] ``--pattern PATTERN, -p PATTERN`` filter the attributes using this pattern ``--overview, -o`` print overview of what attributes an object has ``--verbose, -v`` print full information about attributes ``--all`` print all object attributes ``--attributes ATTRIBUTES, --attrs ATTRIBUTES`` comma separated list of attributes to inspect for object ---- .. _ramble-license: ramble license -------------- list and check license headers on files in ramble .. code-block:: console ramble license [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`license list-files ` * :ref:`license verify ` * :ref:`license update-copyright-year ` ---- .. _ramble-license-list-files: ramble license list-files ^^^^^^^^^^^^^^^^^^^^^^^^^ list files in ramble that should have license headers .. code-block:: console ramble license list-files [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-license-verify: ramble license verify ^^^^^^^^^^^^^^^^^^^^^ verify that files in ramble have the right license header .. code-block:: console ramble license verify [-h] [--root ROOT] [--modified] **Optional arguments** ``-h, --help`` show this help message and exit ``--root ROOT`` scan a different prefix for license issues ``--modified, -m`` verify only the modified files as outputted by `git ls-files --modified` ---- .. _ramble-license-update-copyright-year: ramble license update-copyright-year ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ update copyright header for the current year (utc-based) in all licensed files .. code-block:: console ramble license update-copyright-year [-h] **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-list: ramble list ----------- list and search available objects .. code-block:: console ramble list [-hd] [--format {name_only,version_json,html}] [--update FILE] [-t TAGS] [--type TYPE] ... **Positional arguments** filter optional case-insensitive glob patterns to filter results **Optional arguments** ``-h, --help`` show this help message and exit ``-d, --search-description`` filtering will also search the description for a match ``--format {name_only,version_json,html}`` format to be used to print the output [default: name_only] ``--update FILE`` write output to the specified file, if any object is newer ``-t TAGS, --tags TAGS`` filter a package query by tags ``--type TYPE`` type of objects. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms ---- .. _ramble-mirror: ramble mirror ------------- manage mirrors (inputs) .. code-block:: console ramble mirror [-hn] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit ``-n, --no-checksum`` do not use checksums to verify downloaded files (unsafe) **Subcommands** .. hlist:: :columns: 4 * :ref:`mirror destroy ` * :ref:`mirror add ` * :ref:`mirror remove ` * :ref:`mirror set-url ` * :ref:`mirror list ` ---- .. _ramble-mirror-destroy: ramble mirror destroy ^^^^^^^^^^^^^^^^^^^^^ Given a url, recursively delete everything under it. .. code-block:: console ramble mirror destroy [-h] (-m mirror_name | -u mirror_url) **Optional arguments** ``-h, --help`` show this help message and exit ``-m mirror_name, --mirror-name mirror_name`` find mirror to destroy by name ``-u mirror_url, --mirror-url mirror_url`` find mirror to destroy by url ---- .. _ramble-mirror-add: ramble mirror add ^^^^^^^^^^^^^^^^^ Add a mirror to Ramble. .. code-block:: console ramble mirror add [-h] [--scope {defaults,system,site,user}] mirror url **Positional arguments** mirror mnemonic name for mirror url url of mirror directory from 'ramble mirror create' **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to modify ---- .. _ramble-mirror-remove: ramble mirror remove ^^^^^^^^^^^^^^^^^^^^ Remove a mirror by name. .. code-block:: console ramble mirror remove [-h] [--scope {defaults,system,site,user}] mirror **Positional arguments** mirror mnemonic name for mirror **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to modify ---- .. _ramble-mirror-set-url: ramble mirror set-url ^^^^^^^^^^^^^^^^^^^^^ Change the URL of a mirror. .. code-block:: console ramble mirror set-url [-h] [--push] [--scope {defaults,system,site,user}] mirror url **Positional arguments** mirror mnemonic name for mirror url url of mirror directory from 'ramble mirror create' **Optional arguments** ``-h, --help`` show this help message and exit ``--push`` set only the URL used for uploading new resources ``--scope {defaults,system,site,user}`` configuration scope to modify ---- .. _ramble-mirror-list: ramble mirror list ^^^^^^^^^^^^^^^^^^ Print out available mirrors to the console. .. code-block:: console ramble mirror list [-h] [--scope {defaults,system,site,user}] **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to read from ---- .. _ramble-on: ramble on --------- "And now's the time, the time is now" (execute workspace experiments) .. code-block:: console ramble on [-h] [--executor executor] [--enable-per-experiment-prints] [--suppress-run-header] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] **Optional arguments** ``-h, --help`` show this help message and exit ``--executor executor`` execution template for each experiment ``--enable-per-experiment-prints`` Enable per experiment prints (phases and log paths). ``--suppress-run-header`` Disable the logger header. ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ---- .. _ramble-python: ramble python ------------- launch an interpreter as ramble would launch a command .. code-block:: console ramble python [-hVu] [-c PYTHON_COMMAND] [-i {python,ipython}] [-m MODULE] [--path] ... **Positional arguments** python_args file to run plus arguments **Optional arguments** ``-h, --help`` show this help message and exit ``-V, --version`` print the Python version number and exit ``-c PYTHON_COMMAND`` command to execute ``-u`` for compatibility with xdist, do not use without adding -u to the interpreter ``-i {python,ipython}`` python interpreter ``-m MODULE`` run library module as a script ``--path`` show path to python interpreter that ramble uses ---- .. _ramble-repo: ramble repo ----------- manage Ramble repositories .. code-block:: console ramble repo [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`repo create ` * :ref:`repo list ` * :ref:`repo add ` * :ref:`repo remove ` ---- .. _ramble-repo-create: ramble repo create ^^^^^^^^^^^^^^^^^^ Create a new repository. .. code-block:: console ramble repo create [-h] [-d SUBDIRECTORY] [-t TYPE] directory [new_namespace] **Positional arguments** directory directory to create the repo in new_namespace namespace to identify objects in the repository. defaults to the directory name **Optional arguments** ``-h, --help`` show this help message and exit ``-d SUBDIRECTORY, --subdirectory SUBDIRECTORY`` subdirectory to store objects in the repository. Default is determined by the type of repository. Use an empty string for no subdirectory. ``-t TYPE, --type TYPE`` type of repositories to manage. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms, or any ---- .. _ramble-repo-list: ramble repo list ^^^^^^^^^^^^^^^^ Show registered repositories and their namespaces. .. code-block:: console ramble repo list [-h] [--scope {defaults,system,site,user}] [-t TYPE] **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to read from ``-t TYPE, --type TYPE`` type of repositories to manage. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms, or any ---- .. _ramble-repo-add: ramble repo add ^^^^^^^^^^^^^^^ Add a repository to Ramble's configuration. .. code-block:: console ramble repo add [-h] [--scope {defaults,system,site,user}] [-t TYPE] path **Positional arguments** path path to a Ramble repository directory **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to modify ``-t TYPE, --type TYPE`` type of repositories to manage. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms, or any ---- .. _ramble-repo-remove: ramble repo remove ^^^^^^^^^^^^^^^^^^ Remove a repository from Ramble's configuration. .. code-block:: console ramble repo remove [-h] [--scope {defaults,system,site,user}] [-t TYPE] namespace_or_path **Positional arguments** namespace_or_path namespace or path of a Ramble repository **Optional arguments** ``-h, --help`` show this help message and exit ``--scope {defaults,system,site,user}`` configuration scope to modify ``-t TYPE, --type TYPE`` type of repositories to manage. Defaults to 'applications'. Allowed types are applications, modifiers, package_managers, workflow_managers, systems, platforms, base_classes, base_applications, base_modifiers, base_package_managers, base_workflow_managers, base_systems, base_platforms, or any ---- .. _ramble-results: ramble results -------------- take actions on experiment results .. code-block:: console ramble results [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`results upload ` * :ref:`results index ` * :ref:`results report ` ---- .. _ramble-results-upload: ramble results upload ^^^^^^^^^^^^^^^^^^^^^ Imports Ramble experiment results from JSON file and uploads them as specified in the upload block of Ramble's config file. .. code-block:: console ramble results upload [-h] filename **Positional arguments** filename path of file to upload **Optional arguments** ``-h, --help`` show this help message and exit ---- .. _ramble-results-index: ramble results index ^^^^^^^^^^^^^^^^^^^^ List attributes in results including FOMs and template variables .. code-block:: console ramble results index [-hv] [-f FILE] **Optional arguments** ``-h, --help`` show this help message and exit ``-v, --all-vars`` print all variable names ``-f FILE, --file FILE`` path of results file ---- .. _ramble-results-report: ramble results report ^^^^^^^^^^^^^^^^^^^^^ Create a report with charts from Ramble experiment results. .. code-block:: console ramble results report [-hn] [--workspace WRKSPC] (--strong-scaling STRONG_SCALING [STRONG_SCALING ...] | --weak-scaling WEAK_SCALING [WEAK_SCALING ...] | --multi-line MULTI_LINE [MULTI_LINE ...] | --compare COMPARE [COMPARE ...] | --foms) [--pandas-where WHERE] [--logx] [--logy] [--simplify-names] [--split-by SPLIT_BY] [-f FILE] **Optional arguments** ``-h, --help`` show this help message and exit ``--workspace WRKSPC`` the workspace to report on ``--strong-scaling STRONG_SCALING [STRONG_SCALING ...]`` generate a scaling report, requires two args: [y-axis metric] [x-axis metric][optional: group by] ``--weak-scaling WEAK_SCALING [WEAK_SCALING ...]`` generate a scaling report, requires two args: [y-axis metric] [x-axis metric][optional: group by] ``--multi-line MULTI_LINE [MULTI_LINE ...]`` generate a scaling report, requires two args: [y-axis metric] [x-axis metric][optional: group by] ``--compare COMPARE [COMPARE ...]`` generate a comparison report, requires at least two args: [FOM 1] [Additional FOMs][optional: group by(s)] ``--foms`` generate a FOM report, showing values of FOMs for each experiment ``--pandas-where WHERE`` Down select data to plot (useful for complex workspaces with collisions). Takes pandas query format ``-n, --normalize`` Normalize charts where possible. For scaling charts, this requires fom_type to be specified as either 'time' or 'throughput' in the application definition. ``--logx`` Plot X axis as log ``--logy`` Plot Y axis as log ``--simplify-names`` Simplify experiment names on the x-axis by stripping common prefixes and suffixes ``--split-by SPLIT_BY`` Ramble Variable to split out into different plots ``-f FILE, --file FILE`` path of results file ---- .. _ramble-software-definitions: ramble software-definitions --------------------------- inspect software definitions in object definitions .. code-block:: console ramble software-definitions [-hsce] **Optional arguments** ``-h, --help`` show this help message and exit ``-s, --summary`` print summary of software definitions ``-c, --conflicts`` print summary of conflicting definitions ``-e, --error-on-conflict`` if conflicts are found, exit code is number of conflicts ---- .. _ramble-style: ramble style ------------ runs source code style checks on Ramble. .. code-block:: console ramble style [-haorUfk] [-b BASE] [-t TOOL | -s SKIP] [--repo-path REPO_PATH] [--tool-args TOOL_ARGS] ... **Positional arguments** files specific files to check **Optional arguments** ``-h, --help`` show this help message and exit ``-b BASE, --base BASE`` select base branch for collecting list of modified files ``-a, --all`` check all files, not just changed files ``-o, --output`` send filtered files to stdout as well as temp files ``-r, --root-relative`` print root-relative paths (default: cwd-relative) ``-U, --no-untracked`` exclude untracked files from checks ``-f, --fix`` format automatically if possible with black ``-k, --keep-temp`` do not delete temporary directory where flake8 runs. use for debugging, to see filtered files ``-t TOOL, --tool TOOL`` specify which tools to run (default: isort,black,flake8,mypy,ruff) ``-s SKIP, --skip SKIP`` specify tools to skip (choose from isort,black,flake8,mypy,ruff) ``--repo-path REPO_PATH`` apply style checks and fixes to the given repository ``--tool-args TOOL_ARGS`` specify extra arguments to pass to tools (e.g., --tool-args ruff:'--unsafe-fixes') ---- .. _ramble-unit-test: ramble unit-test ---------------- run ramble's unit tests (wrapper around pytest) .. code-block:: console ramble unit-test [-hHs] [--lib | --obj | -r REPO_PATH] [--perf] [--fast | --slow] [-l | -L | -N] [-k EXPRESSION] [--showlocals] ... **Positional arguments** pytest_args arguments for pytest **Optional arguments** ``-h, --help`` show this help message and exit ``-H, --pytest-help`` show full pytest help, with advanced options ``--lib`` run only tests under the lib directory ``--obj`` run only tests under the builtin object repo directory ``-r REPO_PATH, --repo-path REPO_PATH`` run tests under the given object repo root (used for testing external object repo) ``--perf`` run only performance tests ``--fast`` run only fast tests (skip slow tests) ``--slow`` run only slow tests (skip fast tests) ``-l, --list`` list test filenames ``-L, --list-long`` list all test functions ``-N, --list-names`` list full names of all tests ``-s`` print output while tests run (disable capture) ``-k EXPRESSION`` filter tests by keyword (can also use w/list options) ``--showlocals`` show local variable values in tracebacks ---- .. _ramble-workspace: ramble workspace ---------------- manage experiment workspaces .. code-block:: console ramble workspace [-h] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit **Subcommands** .. hlist:: :columns: 4 * :ref:`workspace activate ` * :ref:`workspace archive ` * :ref:`workspace deactivate ` * :ref:`workspace create ` * :ref:`workspace concretize ` * :ref:`workspace config ` * :ref:`workspace setup ` * :ref:`workspace analyze ` * :ref:`workspace push-to-cache ` * :ref:`workspace info ` * :ref:`workspace edit ` * :ref:`workspace mirror ` * :ref:`workspace experiment-logs ` * :ref:`workspace list ` * :ref:`workspace remove ` * :ref:`workspace generate-config ` * :ref:`workspace manage ` ---- .. _ramble-workspace-activate: ramble workspace activate ^^^^^^^^^^^^^^^^^^^^^^^^^ Set the current workspace .. code-block:: console ramble workspace activate [-hp] [--sh | --csh | --fish | --bat] [--temp] [-d DIR] [--parent-dir dir] [--dry-run] [workspace] **Positional arguments** workspace name of workspace to activate **Optional arguments** ``-h, --help`` show this help message and exit ``--sh`` print sh commands to activate the workspace ``--csh`` print csh commands to activate the workspace ``--fish`` print fish commands to activate the workspace ``--bat`` print bat commands to activate the environment ``-p, --prompt`` decorate the command line prompt when activating ``--temp`` create and activate a workspace in a temporary directory ``-d DIR, --dir DIR`` activate the workspace in this directory ``--parent-dir dir`` parent directory for the named workspace to activate ``--dry-run`` perform a dry run of the activate command ---- .. _ramble-workspace-archive: ramble workspace archive ^^^^^^^^^^^^^^^^^^^^^^^^ archive current workspace state .. code-block:: console ramble workspace archive [-h] [--tar-archive] [--prefix ARCHIVE_PREFIX] [--upload-url UPLOAD_URL] [--include-secrets] [--archive-pattern ARCHIVE_PATTERNS [ARCHIVE_PATTERNS ...]] [--phases PHASES [PHASES ...]] [--include-phase-dependencies] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]] [--profile-phase-output PROFILE_PHASE_OUTPUT] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--tar-archive, -t`` create a tar.gz of the archive directory for backing up. ``--prefix ARCHIVE_PREFIX, -p ARCHIVE_PREFIX`` Specify archive prefix to customize output filename. ``--upload-url UPLOAD_URL, -u UPLOAD_URL`` URL to upload tar archive into. Does nothing if `-t` is not specified. ``--include-secrets`` If set, secrets are included in the archive. Default is false ``--archive-pattern ARCHIVE_PATTERNS [ARCHIVE_PATTERNS ...]`` patterns to specify additionally files that will be included in the archive. Paths are relative to workspace root. ``--phases PHASES [PHASES ...]`` select phases to execute when performing setup. Phase names support globbing ``--include-phase-dependencies`` if set, phase dependencies are automatically added to the list of executed phases ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]`` phases to be profiled by line_profiler ``--profile-phase-output PROFILE_PHASE_OUTPUT`` file path to save the phase line_profiler output ``--dry-run`` perform a dry run of the archive command ---- .. _ramble-workspace-deactivate: ramble workspace deactivate ^^^^^^^^^^^^^^^^^^^^^^^^^^^ deactivate any active workspace in the shell .. code-block:: console ramble workspace deactivate [-h] [--sh | --csh | --fish | --bat] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--sh`` print sh commands to deactivate the workspace ``--csh`` print csh commands to deactivate the workspace ``--fish`` print fish commands to activate the workspace ``--bat`` print bat commands to activate the environment ``--dry-run`` perform a dry run of the deactivate command ---- .. _ramble-workspace-create: ramble workspace create ^^^^^^^^^^^^^^^^^^^^^^^ create a new workspace .. code-block:: console ramble workspace create [-hda] [-c CONFIG] [-t TEMPLATE_EXECUTE] [--software-dir dir] [--inputs-dir dir] [--parent-dir dir] [--dry-run] wrkspc **Positional arguments** wrkspc name of workspace to create **Optional arguments** ``-h, --help`` show this help message and exit ``-c CONFIG, --config CONFIG`` configuration file to create workspace with ``-t TEMPLATE_EXECUTE, --template_execute TEMPLATE_EXECUTE`` execution template file to use when creating workspace ``-d, --dir`` create a workspace in a specific directory ``--software-dir dir`` external directory to link as software directory in workspace ``--inputs-dir dir`` external directory to link as inputs directory in workspace ``--parent-dir dir`` parent directory for the new named workspace (must be in workspace_dirs) ``-a, --activate`` activate the created workspace, if specified. Default is false ``--dry-run`` perform a dry run of the create command ---- .. _ramble-workspace-concretize: ramble workspace concretize ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Concretize a workspace .. code-block:: console ramble workspace concretize [-hf] [--simplify] [--quiet] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``-f, --force-concretize`` Overwrite software environment configuration with defaults defined in application definition ``--simplify`` Remove unused software and experiment templates from workspace config ``--quiet, -q`` Silently ignore conflicting package definitions ``--dry-run`` perform a dry run of the concretize command ---- .. _ramble-workspace-config: ramble workspace config ^^^^^^^^^^^^^^^^^^^^^^^ Squashed workspace config .. code-block:: console ramble workspace config [-h] (--print-squash | --simplify-software | --simplify-variables) [--include-section INCLUDED_SECTION [INCLUDED_SECTION ...]] [--exclude-section EXCLUDED_SECTION [EXCLUDED_SECTION ...]] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--print-squash, -p`` Print a squashed workspace configuration ``--simplify-software, --ss`` Simplify the software configuration section of this workspace ``--simplify-variables, --sv`` Simplify the variables configuration section of this workspace ``--include-section INCLUDED_SECTION [INCLUDED_SECTION ...], -i INCLUDED_SECTION [INCLUDED_SECTION ...]`` list of patterns to include configuration section, when printing the squashed config ``--exclude-section EXCLUDED_SECTION [EXCLUDED_SECTION ...], -e EXCLUDED_SECTION [EXCLUDED_SECTION ...]`` list of patterns to exclude configuration section, when printing the squashed config. Overrides included section. ``--dry-run`` perform a dry run of the config command ---- .. _ramble-workspace-setup: ramble workspace setup ^^^^^^^^^^^^^^^^^^^^^^ Setup a workspace .. code-block:: console ramble workspace setup [-h] [--dry-run] [--phases PHASES [PHASES ...]] [--include-phase-dependencies] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] [--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]] [--profile-phase-output PROFILE_PHASE_OUTPUT] **Optional arguments** ``-h, --help`` show this help message and exit ``--dry-run`` perform a dry run. Sets up directories and generates all scripts. Prints commands that would be executed for installation, and files that would be downloaded. ``--phases PHASES [PHASES ...]`` select phases to execute when performing setup. Phase names support globbing ``--include-phase-dependencies`` if set, phase dependencies are automatically added to the list of executed phases ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ``--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]`` phases to be profiled by line_profiler ``--profile-phase-output PROFILE_PHASE_OUTPUT`` file path to save the phase line_profiler output ---- .. _ramble-workspace-analyze: ramble workspace analyze ^^^^^^^^^^^^^^^^^^^^^^^^ Analyze a workspace .. code-block:: console ramble workspace analyze [-hups] [-f OUTPUT_FORMATS [OUTPUT_FORMATS ...]] [--fom-origin-types FOM_ORIGIN_TYPES [FOM_ORIGIN_TYPES ...]] [--phases PHASES [PHASES ...]] [--include-phase-dependencies] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] [--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]] [--profile-phase-output PROFILE_PHASE_OUTPUT] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``-f OUTPUT_FORMATS [OUTPUT_FORMATS ...], --formats OUTPUT_FORMATS [OUTPUT_FORMATS ...]`` list of output formats to write.Supported formats are json, yaml, or text ``-u, --upload`` Push experiment data to remote store (as defined in config) ``-p, --print-results`` print out the analysis result ``--fom-origin-types FOM_ORIGIN_TYPES [FOM_ORIGIN_TYPES ...]`` FOM origin types to include in analysis output. Accepts space-delimited lists and can be specified multiple times. ``-s, --summary-only`` print out only the summary stats for repeated experiments ``--phases PHASES [PHASES ...]`` select phases to execute when performing setup. Phase names support globbing ``--include-phase-dependencies`` if set, phase dependencies are automatically added to the list of executed phases ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ``--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]`` phases to be profiled by line_profiler ``--profile-phase-output PROFILE_PHASE_OUTPUT`` file path to save the phase line_profiler output ``--dry-run`` perform a dry run of the analyze command ---- .. _ramble-workspace-push-to-cache: ramble workspace push-to-cache ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ push workspace envs to a given buildcache .. code-block:: console ramble workspace push-to-cache [-h] [--dry-run] -d CACHE_PATH [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] [--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]] [--profile-phase-output PROFILE_PHASE_OUTPUT] **Optional arguments** ``-h, --help`` show this help message and exit ``--dry-run`` perform a dry run. Acts like it will push to a cache, but will not actually create a cache. ``-d CACHE_PATH`` Path to cache. ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ``--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]`` phases to be profiled by line_profiler ``--profile-phase-output PROFILE_PHASE_OUTPUT`` file path to save the phase line_profiler output ---- .. _ramble-workspace-info: ramble workspace info ^^^^^^^^^^^^^^^^^^^^^ Information about a workspace .. code-block:: console ramble workspace info [-hv] [--software | --all-software] [--templates] [--expansions] [--tags] [--phases] [--variants] [--executables] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--software`` If set, used software stack information will be printed ``--all-software`` If set, all software stack information will be printed ``--templates`` If set, workspace templates will be printed ``--expansions`` If set, variable expansions will be printed ``--tags`` If set, experiment tags will be printed ``--phases`` If set, phase information will be printed ``--variants`` If set, experiment variants will be printed ``--executables`` If set, experiment executables will be printed ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ``-v, --verbose`` level of verbosity. Add flags to increase description of workspace level 1 enables software, tags, templates, and variants level 2 enables executables, expansions, and phases ``--dry-run`` perform a dry run of the info command ---- .. _ramble-workspace-edit: ramble workspace edit ^^^^^^^^^^^^^^^^^^^^^ edit workspace config or template .. code-block:: console ramble workspace edit [-hctlp] [-f FILENAME] [--all] [--dry-run] ... **Positional arguments** editor_args Arguments to pass into editor, following the list of files **Optional arguments** ``-h, --help`` show this help message and exit ``-f FILENAME, --file FILENAME`` Open a single file by filename ``-c, --config-only`` Only open config files ``-t, --template-only`` Only open template files ``-l, --license-only`` Only open license config files ``--all`` Open all yaml and template files in workspace config directory ``-p, --print-file`` print the file name that would be edited ``--dry-run`` perform a dry run of the edit command ---- .. _ramble-workspace-mirror: ramble workspace mirror ^^^^^^^^^^^^^^^^^^^^^^^ mirror current workspace state .. code-block:: console ramble workspace mirror [-h] -d MIRROR_PATH [--dry-run] [--phases PHASES [PHASES ...]] [--include-phase-dependencies] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]] [--profile-phase-output PROFILE_PHASE_OUTPUT] **Optional arguments** ``-h, --help`` show this help message and exit ``-d MIRROR_PATH`` Path to create mirror in. ``--dry-run`` perform a dry run. Creates package environments, prints package manager specific commands that would be executed for creating the mirror. ``--phases PHASES [PHASES ...]`` select phases to execute when performing setup. Phase names support globbing ``--include-phase-dependencies`` if set, phase dependencies are automatically added to the list of executed phases ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--profile-phase PROFILE_PHASES [PROFILE_PHASES ...]`` phases to be profiled by line_profiler ``--profile-phase-output PROFILE_PHASE_OUTPUT`` file path to save the phase line_profiler output ---- .. _ramble-workspace-experiment-logs: ramble workspace experiment-logs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ print log information for workspace .. code-block:: console ramble workspace experiment-logs [-h] [--limit-one | --first-failed | --failed] [--where WHERE [WHERE ...]] [--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]] [--filter-tags FILTER_TAGS [FILTER_TAGS ...]] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--limit-one`` only print the first log information block ``--first-failed`` only print the information for the first failed experiment. Requires `ramble workspace analyze` to have been run previously ``--failed`` print only failed experiment logs ``--where WHERE [WHERE ...]`` inclusive filter on experiments where the provided logical statement is True ``--exclude-where EXCLUDE_WHERE [EXCLUDE_WHERE ...]`` exclusive filter experiments where the provided logical statement is True ``--filter-tags FILTER_TAGS [FILTER_TAGS ...]`` filter experiments to only those that include the provided tags ``--dry-run`` perform a dry run of the experiment-logs command ---- .. _ramble-workspace-list: ramble workspace list ^^^^^^^^^^^^^^^^^^^^^ list available workspaces .. code-block:: console ramble workspace list [-h] [--parent-dir dir] [--merged] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--parent-dir dir`` filter workspaces by parent directory ``--merged`` list a merged set of workspaces across all parent directories ``--dry-run`` perform a dry run of the list command ---- .. _ramble-workspace-remove: ramble workspace remove ^^^^^^^^^^^^^^^^^^^^^^^ remove an existing workspace .. code-block:: console ramble workspace remove [-hy] [--dry-run] workspace [workspace ...] **Positional arguments** workspace workspace(s) to remove **Optional arguments** ``-h, --help`` show this help message and exit ``-y, --yes-to-all`` assume "yes" is the answer to every confirmation request ``--dry-run`` perform a dry run of the remove command ---- .. _ramble-workspace-generate-config: ramble workspace generate-config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ generate current workspace config .. code-block:: console ramble workspace generate-config [-h] [--workload-filter WORKLOAD_FILTERS] [--variable-filter VARIABLE_FILTERS] [--variable-definition VARIABLE_DEFINITIONS] [--variant-definition VARIANT_DEFINITIONS] [--experiment-name EXPERIMENT_NAME] [--package-manager PACKAGE_MANAGER] [--workflow-manager WORKFLOW_MANAGER] [--dry-run] [--overwrite] [--include-default-variables | --workload-name-variable VAR] [--zip ZIPS] [--matrix MATRIX] [--default-variable-value DEFAULT_VARIABLE_VALUE] application **Positional arguments** application application name **Optional arguments** ``-h, --help`` show this help message and exit ``--workload-filter WORKLOAD_FILTERS, --wf WORKLOAD_FILTERS`` glob filter to use when selecting workloads in the application. Workload is kept if it matches any filter. ``--variable-filter VARIABLE_FILTERS, --vf VARIABLE_FILTERS`` glob filter to use when selecting variables in the workloads. Variable is kept if it matches any filter. ``--variable-definition VARIABLE_DEFINITIONS, -v VARIABLE_DEFINITIONS`` variable definition to set in the generated experiments. Given in the form key=value ``--variant-definition VARIANT_DEFINITIONS, -V VARIANT_DEFINITIONS`` variant definition to set in the generated experiments. Given in the form name=value ``--experiment-name EXPERIMENT_NAME, -e EXPERIMENT_NAME`` name of generated experiment ``--package-manager PACKAGE_MANAGER, -p PACKAGE_MANAGER`` (DEPRECATED) name of (optional) package manager to use within the experiment scope ``--workflow-manager WORKFLOW_MANAGER, --wm WORKFLOW_MANAGER`` (DEPRECATED) name of (optional) workflow manager to use within the experiment scope ``--dry-run, --print`` perform a dry run. Print resulting config to screen and not to the workspace configuration file ``--overwrite`` overwrite existing definitions with newly generated definitions ``--include-default-variables, -i`` whether to include default variable values in the resulting config ``--workload-name-variable VAR, -w VAR`` variable name to collapse workloads in ``--zip ZIPS, -z ZIPS`` zip to define for the experiments, in the format zipname=[zipvar1,zipvar2] ``--matrix MATRIX, -m MATRIX`` comma delimited list of variable names to matrix in the experiments ``--default-variable-value DEFAULT_VARIABLE_VALUE`` default value for any required, but undefined, variable. Default is '' which is likely to cause validation errors ---- .. _ramble-workspace-manage: ramble workspace manage ^^^^^^^^^^^^^^^^^^^^^^^ manage workspace definitions .. code-block:: console ramble workspace manage [-h] [--dry-run] SUBCOMMAND ... **Optional arguments** ``-h, --help`` show this help message and exit ``--dry-run`` perform a dry run of the manage command **Subcommands** .. hlist:: :columns: 4 * :ref:`workspace manage experiments ` * :ref:`workspace manage software ` * :ref:`workspace manage includes ` * :ref:`workspace manage modifiers ` ---- .. _ramble-workspace-manage-experiments: ramble workspace manage experiments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ manage experiment definitions .. code-block:: console ramble workspace manage experiments [-h] [--workload-filter WORKLOAD_FILTERS] [--variable-filter VARIABLE_FILTERS] [--variable-definition VARIABLE_DEFINITIONS] [--variant-definition VARIANT_DEFINITIONS] [--experiment-name EXPERIMENT_NAME] [--package-manager PACKAGE_MANAGER] [--workflow-manager WORKFLOW_MANAGER] [--dry-run] [--overwrite] [--include-default-variables | --workload-name-variable VAR] [--zip ZIPS] [--matrix MATRIX] [--default-variable-value DEFAULT_VARIABLE_VALUE] application **Positional arguments** application application name **Optional arguments** ``-h, --help`` show this help message and exit ``--workload-filter WORKLOAD_FILTERS, --wf WORKLOAD_FILTERS`` glob filter to use when selecting workloads in the application. Workload is kept if it matches any filter. ``--variable-filter VARIABLE_FILTERS, --vf VARIABLE_FILTERS`` glob filter to use when selecting variables in the workloads. Variable is kept if it matches any filter. ``--variable-definition VARIABLE_DEFINITIONS, -v VARIABLE_DEFINITIONS`` variable definition to set in the generated experiments. Given in the form key=value ``--variant-definition VARIANT_DEFINITIONS, -V VARIANT_DEFINITIONS`` variant definition to set in the generated experiments. Given in the form name=value ``--experiment-name EXPERIMENT_NAME, -e EXPERIMENT_NAME`` name of generated experiment ``--package-manager PACKAGE_MANAGER, -p PACKAGE_MANAGER`` (DEPRECATED) name of (optional) package manager to use within the experiment scope ``--workflow-manager WORKFLOW_MANAGER, --wm WORKFLOW_MANAGER`` (DEPRECATED) name of (optional) workflow manager to use within the experiment scope ``--dry-run, --print`` perform a dry run. Print resulting config to screen and not to the workspace configuration file ``--overwrite`` overwrite existing definitions with newly generated definitions ``--include-default-variables, -i`` whether to include default variable values in the resulting config ``--workload-name-variable VAR, -w VAR`` variable name to collapse workloads in ``--zip ZIPS, -z ZIPS`` zip to define for the experiments, in the format zipname=[zipvar1,zipvar2] ``--matrix MATRIX, -m MATRIX`` comma delimited list of variable names to matrix in the experiments ``--default-variable-value DEFAULT_VARIABLE_VALUE`` default value for any required, but undefined, variable. Default is '' which is likely to cause validation errors ---- .. _ramble-workspace-manage-software: ramble workspace manage software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ manage workspace software definitions .. code-block:: console ramble workspace manage software [-h] [--environment-name ENV] [--environment-packages PKG1,PKG2,PKG2 | --external-env PATH] [--package-name NAME] [--package-spec SPEC] [--compiler-package PKG] [--compiler-spec SPEC] [--package-manager-prefix PREFIX] [--remove | --overwrite] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--environment-name ENV, --env ENV`` Name of environment to define ``--environment-packages PKG1,PKG2,PKG2`` Comma separated list of packages to add into environment ``--external-env PATH`` Path to external environment description ``--package-name NAME, --pkg NAME`` Name of package to define ``--package-spec SPEC, --pkg-spec SPEC, --spec SPEC`` Value for the pkg_spec attribute in the defined package ``--compiler-package PKG, --compiler-pkg PKG, --compiler PKG`` Value for the compiler attribute in the defined package ``--compiler-spec SPEC`` Value for the compiler_spec attribute in the defined package ``--package-manager-prefix PREFIX, --prefix PREFIX`` Prefix for defined package attributes. Resulting attributes will be {prefix}_pkg_spec. ``--remove, --delete`` Whether to remove named package and environment definitions if they exist. ``--overwrite, -o`` Whether to overwrite existing definitions or not. ``--dry-run, --print`` perform a dry run. Print resulting config to screen and not to the workspace configuration file ---- .. _ramble-workspace-manage-includes: ramble workspace manage includes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ manage workspace includes .. code-block:: console ramble workspace manage includes [-h] [--list | --remove PATTERN | --remove-index IDX | --add PATH] **Optional arguments** ``-h, --help`` show this help message and exit ``--list, -l`` whether to print existing includes ``--remove PATTERN, -r PATTERN`` whether to remove an existing include by name / pattern ``--remove-index IDX`` whether to remove an existing include by index ``--add PATH, -a PATH`` whether to add a new include ---- .. _ramble-workspace-manage-modifiers: ramble workspace manage modifiers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ manage workspace modifiers .. code-block:: console ramble workspace manage modifiers [-h] (--list | --add | --remove) [--mod-index INDEX] [--scope SCOPE] [--name NAME] [--mode MODE] [--on-executable EXEC_LIST] [--dry-run] **Optional arguments** ``-h, --help`` show this help message and exit ``--list, -l`` whether to print existing modifiers ``--add`` whether to remove an existing modifier by index ``--remove`` whether to remove an existing modifier by index ``--mod-index INDEX, -i INDEX`` index of modifier to remove, only used with --remove ``--scope SCOPE, -s SCOPE`` scope of modifier to manage. Can be a glob when removing. Of the form :: or 'workspace' to manage workspace modifiers. ``--name NAME, -n NAME`` name of modifier to manage. Can be a glob when removing, and defaults to '*'. Should be the name of a modifier object. ``--mode MODE, -m MODE`` mode of modifier to manage. Can be a glob when removing, and defaults to None, using the default for the modifier. ``--on-executable EXEC_LIST, -e EXEC_LIST`` list of 'on_executable' strings to apply for a new modifier. Ignored when removing. Should be of the form '[,,...]' ``--dry-run`` whether to print the config without editing it, or to edit it directly.