Command Line Interface (CLI)¶
yggdrasil
Command¶
usage: yggdrasil [-h] [--version]
{run,info,validate,compile-model,compile,clean,install,config,schema,model-form-schema,dev-update,timing,gha,integration-service-manager,coveragerc,fconvert}
...
Named Arguments¶
- --version
show program’s version number and exit
subcommands¶
- subcommand
Possible choices: run, info, validate, compile-model, compile, clean, install, config, schema, model-form-schema, dev-update, timing, gha, integration-service-manager, coveragerc, fconvert
Sub-commands¶
run¶
Run an integration.
yggdrasil run [-h] [--with-mpi WITH_MPI] [--mpi-tag-start MPI_TAG_START]
[--validate] [--with-debugger WITH_DEBUGGER]
[--disable-python-c-api] [--with-asan] [--as-service]
[--partial-commtype PARTIAL_COMMTYPE] [--client-id CLIENT_ID]
[--loglevel LOGLEVEL] [--rmq-loglevel RMQ_LOGLEVEL]
[--client-loglevel CLIENT_LOGLEVEL] [--validate-components]
[--validate-messages {False,True,First}] [--namespace NAMESPACE]
[--host HOST] [--vhost VHOST] [--user USER]
[--password PASSWORD] [--cluster CLUSTER]
[--default-comm DEFAULT_COMM] [--production-run] [--debug]
yamlfile [yamlfile ...]
Positional Arguments¶
- yamlfile
One or more yaml specification files.
Named Arguments¶
- --with-mpi, --mpi-nproc
Number of MPI processes to run on.
Default: 1
- --mpi-tag-start
Tag that MPI communications should start at.
Default: 0
- --validate
Validate the run via model validation commands on completion.
Default: False
- --with-debugger
Run all models with a specific debuggin tool. If quoted, this can also include flags for the tool.
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile models with the address sanitizer enabled.
Default: False
- --as-service
Run the provided YAMLs as a service.
Default: False
- --partial-commtype
Type of communicator to use for partial comms when –as-service is passed
Default: “rest”
- --client-id
ID associated with the client requesting a service. (This should only be passed when running with –as-service)
- --loglevel
Logging level for yggdrasil operations.
- --rmq-loglevel, --rmqloglevel
Logging level for RabbitMQ operations.
- --client-loglevel, --clientloglevel
Logging level for yggdrasil operations on model processes.
- --validate-components, --validatecomponents
Validate components on creation using their JSON schema (Decreases performance).
Default: False
- --validate-messages, --validatemessages
Possible choices: False, True, First
Which messages should be validated during communication. ‘True’: all messages (decreases performance), ‘False’: no messages, or ‘First’: only the first message a comm sends/receives.
- --namespace
RabbitMQ namespace.
- --host
RabbitMQ host address.
- --vhost
RabbitMQ virtual host address.
- --user
RabbitMQ username.
- --password
RabbitMQ password.
- --cluster
Cluster that should be used.
- --default-comm, --defaultcomm
Comm type that should be used by default.
- --production-run
Turn off safe guards in order to improve performance. This is equivalent to ‘–validate-components –validate-messages=True’
Default: False
- --debug
Turn on debugging utilties including increased logging and validation. This is equivalent to ‘–loglevel=DEBUG –client-loglevel=DEBUG –validate-components=False –validate-messages=False’
Default: False
info¶
Display information about the current yggdrasil installation.
yggdrasil info [-h] [--no-languages] [--no-comms] [--verbose]
{compiler,linker,archiver} ...
Named Arguments¶
- --no-languages
Don’t print information about individual languages.
Default: False
- --no-comms
Don’t print information about individual comms.
Default: False
- --verbose, -v
Increase the verbosity of the printed information.
Default: False
tool¶
Compilation tool types to get info about.
- tool
Possible choices: compiler, linker, archiver
Sub-commands¶
compiler¶
Get information about a compiler.
yggdrasil info compiler [-h] [--toolname TOOLNAME] [--flags] [--fullpath]
[--disable-python-c-api] [--with-asan]
{c,c++,cpp,cxx,fortran}
Positional Arguments¶
- language
Possible choices: c, c++, cpp, cxx, fortran
Language to get tool information for.
Named Arguments¶
- --toolname
Name of tool to get information for. If not provided, information for the default tool will be returned.
- --flags
Display the flags that yggdrasil will pass to the tool when it is called.
Default: False
- --fullpath
Get the full path to the tool exectuable.
Default: False
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
linker¶
Get information about a linker.
yggdrasil info linker [-h] [--toolname TOOLNAME] [--flags] [--fullpath]
[--disable-python-c-api] [--with-asan] [--library]
{c,c++,cpp,cxx,fortran}
Positional Arguments¶
- language
Possible choices: c, c++, cpp, cxx, fortran
Language to get tool information for.
Named Arguments¶
- --toolname
Name of tool to get information for. If not provided, information for the default tool will be returned.
- --flags
Display the flags that yggdrasil will pass to the tool when it is called.
Default: False
- --fullpath
Get the full path to the tool exectuable.
Default: False
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
- --library
Get flags for linking a library.
Default: False
archiver¶
Get information about a archiver.
yggdrasil info archiver [-h] [--toolname TOOLNAME] [--flags] [--fullpath]
[--disable-python-c-api] [--with-asan]
{c,c++,cpp,cxx,fortran}
Positional Arguments¶
- language
Possible choices: c, c++, cpp, cxx, fortran
Language to get tool information for.
Named Arguments¶
- --toolname
Name of tool to get information for. If not provided, information for the default tool will be returned.
- --flags
Display the flags that yggdrasil will pass to the tool when it is called.
Default: False
- --fullpath
Get the full path to the tool exectuable.
Default: False
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
validate¶
Validate a set of YAML specification files for an integration.
yggdrasil validate [-h] [--model-only] [--model-submission]
yamlfile [yamlfile ...]
Positional Arguments¶
- yamlfile
One or more YAML specification files.
Named Arguments¶
- --model-only
Validate a YAML containing an isolated model without ensuring that it is part of a complete integration.
Default: False
- --model-submission
Validate a YAML against the requirements for submissions to the yggdrasil model repository.
Default: False
compile-model¶
Compile a program from source files for use in an yggdrasil integration.
yggdrasil compile-model [-h] [--language {None,c,c++,cpp,cxx,fortran,R,r}]
[--toolname TOOLNAME] [--flags [FLAGS [FLAGS ...]]]
[--use-ccache] [--Rpkg-language RPKG_LANGUAGE]
[--disable-python-c-api] [--with-asan]
source [source ...]
Positional Arguments¶
- source
One or more source files or the directory containing an R package.
Named Arguments¶
- --language
Possible choices: None, c, c++, cpp, cxx, fortran, R, r
Language of the source code. If not provided, the language will be determined from the source extension.
- --toolname
Name of compilation tool that should be used
- --flags
Additional flags that should be added to the compilation command
- --use-ccache
Run compilation with ccache.
Default: False
- --Rpkg-language
Language that R package is written in (only used if the specified language is R).
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
compile¶
Compile yggdrasil dependency libraries. Existing libraries are first deleted.
yggdrasil compile [-h] [--toolname TOOLNAME] [--disable-python-c-api]
[--with-asan] [--force-source]
[--source-language SOURCE_LANGUAGE]
[--flags [FLAGS [FLAGS ...]]] [--use-ccache]
[--Rpkg-language RPKG_LANGUAGE]
[language [language ...]]
Positional Arguments¶
- language
One or more languages to compile dependencies for, source files to compile into an executable, or the directory containing an R package.
Default: [‘all’]
Named Arguments¶
- --toolname
Name of compilation tool that should be used
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
- --force-source
Force all arguments passed to the language parameter to be treated as source files to be compiled.
Default: False
- --source-language
Language of the source code. If not provided, the language will be determined from the source extension.
- --flags
Additional flags that should be added to the compilation command if source files are provided.
- --use-ccache
Run source compilation with ccache.
Default: False
- --Rpkg-language
Language that R package is written in (only used if the provided source language is R).
clean¶
Remove dependency libraries compiled by yggdrasil.
yggdrasil clean [-h] [language [language ...]]
Positional Arguments¶
- language
One or more languages to clean up dependencies for.
Default: [‘all’]
install¶
Complete yggdrasil installation for one or more languages.
yggdrasil install [-h] [--no-import] [--with-asan] [languages [languages ...]]
Positional Arguments¶
- languages
One or more languages that should be installed.
Default: []
Named Arguments¶
- --no-import
Don’t import the yggdrasil package in calling the installation script.
Default: False
- --with-asan
Load ASAN library before running executables.
Default: False
config¶
Update the user config file.
yggdrasil config [-h] [--languages LANGUAGES_FLAG [LANGUAGES_FLAG ...]]
[--show-file] [--remove-file] [--overwrite]
[--disable-languages {c,c++,cpp,cxx,fortran,R,julia,matlab,python,r,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} [{c,c++,cpp,cxx,fortran,R,julia,matlab,python,r,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} ...]]
[--enable-languages {c,c++,cpp,cxx,fortran,R,julia,matlab,python,r,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} [{c,c++,cpp,cxx,fortran,R,julia,matlab,python,r,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} ...]]
[--quiet] [--allow-multiple-omp] [--dont-allow-multiple-omp]
[--c-compiler C_COMPILER] [--c++-compiler C++_COMPILER]
[--fortran-compiler FORTRAN_COMPILER] [--c-linker C_LINKER]
[--c++-linker C++_LINKER] [--fortran-linker FORTRAN_LINKER]
[--c-archiver C_ARCHIVER] [--c++-archiver C++_ARCHIVER]
[--fortran-archiver FORTRAN_ARCHIVER]
[--disable-matlab-engine-for-python]
[--enable-matlab-engine-for-python] [--hide-matlab-libiomp]
[--restore-matlab-libiomp] [--osr-repository-path REPOSITORY]
[languages [languages ...]]
Positional Arguments¶
- languages
One or more languages that should be configured.
Default: [‘all’]
Named Arguments¶
- --languages
One or more languages that should be configured.
Default: [‘all’]
- --show-file
Print the path to the config file without updating it.
Default: False
- --remove-file
Remove the existing config file and return.
Default: False
- --overwrite
Overwrite the existing file.
Default: False
- --disable-languages
Possible choices: c, c++, cpp, cxx, fortran, R, julia, matlab, python, r, cmake, make, lpy, osr, pytorch, sbml, dummy, executable, mpi, timesync
One or more languages that should be disabled.
Default: []
- --enable-languages
Possible choices: c, c++, cpp, cxx, fortran, R, julia, matlab, python, r, cmake, make, lpy, osr, pytorch, sbml, dummy, executable, mpi, timesync
One or more languages that should be enabled.
Default: []
- --quiet, -q
Suppress output.
Default: False
- --allow-multiple-omp
Have yggdrasil set the environment variable KMP_DUPLICATE_LIB_OK to ‘True’ during model runs to disable errors resembling “OMP: Error #15: Initializing libomp.dylib…” that result from having multiple versions of OpenMP loaded during runtime.
- --dont-allow-multiple-omp
Don’t set the KMP_DUPLICATE_LIB_OK environment variable when running models (see help for ‘–allow-multiple-omp’ for more information).
- --c-compiler
Name or path to compiler that should be used to compile models written in c.
- --c++-compiler
Name or path to compiler that should be used to compile models written in c++.
- --fortran-compiler
Name or path to compiler that should be used to compile models written in fortran.
- --c-linker
Name or path to linker that should be used to link models written in c.
- --c++-linker
Name or path to linker that should be used to link models written in c++.
- --fortran-linker
Name or path to linker that should be used to link models written in fortran.
- --c-archiver
Name or path to archiver that should be used to create static libraries for models written in c.
- --c++-archiver
Name or path to archiver that should be used to create static libraries for models written in c++.
- --fortran-archiver
Name or path to archiver that should be used to create static libraries for models written in fortran.
- --disable-matlab-engine-for-python
Disable use of the Matlab engine for Python.
- --enable-matlab-engine-for-python
Enable use of the Matlab engine for Python.
- --hide-matlab-libiomp
Hide the version of libiomp installed by Matlab by slightly changing the filename so that the conda version of libomp is used instead. This helps to solve the error “OMP: Error #15: Initializing libomp.dylib…” that can occur when using a conda environment. The hidden file location will be set in the configuration file and can be restored via the ‘–restore-matlab-libiomp’ option.
- --restore-matlab-libiomp
Restore the version of libiomp installed by Matlab. (See help for ‘–hide-matlab-libiomp’)
- --osr-repository-path
The full path to the OpenSimRoot repository.
schema¶
Regenerate the yggdrasil schema.
yggdrasil schema [-h] [--only-constants] [--filename FILENAME]
Named Arguments¶
- --only-constants
Only update the constants.py file without updating the schema.
Default: False
- --filename
Name where schema should be saved.
model-form-schema¶
Save/print the JSON schema for generating the model specification form.
yggdrasil model-form-schema [-h] [--file FILE]
Named Arguments¶
- --file
Path to file where the schema should be saved.
dev-update¶
Perform cleanup and reinitialization following an update to the code during development.
yggdrasil dev-update [-h]
timing¶
Create performance plots using timing results.
yggdrasil timing [-h] {commtype,language,os,python,lang2019} ...
comparison¶
Comparison plot that should be created.
- comparison
Possible choices: commtype, language, os, python, lang2019
Sub-commands¶
commtype¶
Compare different communication avenues.
yggdrasil timing commtype [-h]
language¶
Compare different programming languages.
yggdrasil timing language [-h]
os¶
Compare different operating systems.
yggdrasil timing os [-h]
python¶
Compare different versions of Python.
yggdrasil timing python [-h]
lang2019¶
Create plots from Lang (2019) paper.
yggdrasil timing lang2019 [-h]
gha¶
Generate a Github Actions (GHA) workflow yaml file from a version of the file that uses anchors (not supported by GHA as of 2021-01-14).
yggdrasil gha [-h] [--base BASE] [--dest DEST] [--verbose]
Named Arguments¶
- --base, --base-file
Version of GHA workflow yaml that contains anchors.
- --dest
Name of target GHA workflow yaml file.
- --verbose
Print yaml contents.
Default: False
integration-service-manager¶
Start or manage a integration service manager.
yggdrasil integration-service-manager [-h] [--manager-name MANAGER_NAME]
[--service-type {flask,rmq}]
[--commtype COMMTYPE]
[--address ADDRESS] [--port PORT]
{start,stop,status,register,unregister}
...
Named Arguments¶
- --manager-name
Name that will be used to identify the service manager.
- --service-type
Possible choices: flask, rmq
Type of service that should be started. If not provided, the default will be the (‘services’, ‘default_type’) configuration option, if set, and will otherwise be ‘flask’.
- --commtype
Type of communicator that should be used for connections to services. If not provided, the default will be determined by the (‘services’, ‘default_comm’) configuration option, if set.
- --address
URL for requests to the service manager. If not provided, the default will be determined by the (‘services’, ‘default_type’) configuration option, if set, and based on the selected ‘service-type’, if not. For a service-type of ‘flask’, this should be the http address with the port that should be used and the default will be ‘http://localhost:{port}’. For a service-type of ‘rmq’, this should be an amqp broker address and the default will be ‘amqp://guest:guest@localhost:{port}/%2f’.
- --port
Port that should be used to access the app. Defaults to 5000 for a flask service manager and 5672 for a RabbitMQ service manager if not set via the PORT environment variable.
action¶
Management action to take.
- action
Possible choices: start, stop, status, register, unregister
Sub-commands¶
start¶
Start an integration service manager and/or integration service.
yggdrasil integration-service-manager start [-h] [--remote-url REMOTE_URL]
[--integration-name INTEGRATION_NAME]
[--integration-yamls INTEGRATION_YAMLS [INTEGRATION_YAMLS ...]]
[--with-coverage]
[--model-repository MODEL_REPOSITORY]
[--track-memory]
[--log-level LOG_LEVEL]
Named Arguments¶
- --remote-url
URL that will be used to access the service manager and running integrations by remote requests. If not provided, the environment variable YGGDRASIL_SERVICE_HOST_URL will be used if it is set. If it is not set, the local
address
will be used under the assumption that the service manager and integration services will only be connected to by local integrations.- --integration-name
Name of integration to start. If not provided, a service manager will be started.
- --integration-yamls
One or more YAML specification files defining the integration. This argument may be omitted if ‘name’ refers to a registered integration.
- --with-coverage
Enable coverage cleanup for testing.
Default: False
- --model-repository
URL for a directory in a Git repository containing models that should be loaded into the service manager registry.
- --track-memory
Track the memory used by the service manager.
Default: False
- --log-level
Level of logging that should be performed for the service manager application.
stop¶
Stop an integration service manager or an integration service.
yggdrasil integration-service-manager stop [-h]
[--integration-name INTEGRATION_NAME]
Named Arguments¶
- --integration-name
Name of integration to stop. If not provided, the service manager will be stopped as will all of the running services.
status¶
Get list of available services and the status of any running services.
yggdrasil integration-service-manager status [-h]
register¶
Register an integration with the service manager.
yggdrasil integration-service-manager register [-h]
integration-name
[integration-yamls [integration-yamls ...]]
Positional Arguments¶
- integration-name
The name that the integration should be registered under or the path to a YAML file containing a list of one or more mappings between name and YAML specification files for integrations that should be registered.
- integration-yamls
One or more YAML specification files defining the integration.
unregister¶
Unregister an integration with the service manager.
yggdrasil integration-service-manager unregister [-h] integration-name
Positional Arguments¶
- integration-name
The name of the integration to remove from the registry or the path to a YAML file containing a list of one or more mappings between integration name and YAML specification files for integrations that should be unregistered.
coveragerc¶
Generate a coveragerc file that covers/ignores lines based on installed languages or options.
yggdrasil coveragerc [-h] [--method {installed,env,None}]
[--cover-languages [{c,c++,fortran,R,julia,matlab,python,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} [{c,c++,fortran,R,julia,matlab,python,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} ...]]]
[--dont-cover-languages [{c,c++,fortran,R,julia,matlab,python,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} [{c,c++,fortran,R,julia,matlab,python,cmake,make,lpy,osr,pytorch,sbml,dummy,executable,mpi,timesync} ...]]]
[--filename FILENAME] [--setup-cfg SETUP_CFG]
Named Arguments¶
- --method
Possible choices: installed, env, None
Method that should be used to select languages that should be covered. ‘env’ covers languages based on the value of environment variables of the form ‘INSTALL{language}’. ‘installed’ covers languages that yggdrasil considers installed.
- --cover-languages, --cover-language, --cover
Possible choices: c, c++, fortran, R, julia, matlab, python, cmake, make, lpy, osr, pytorch, sbml, dummy, executable, mpi, timesync
Language(s) to cover.
- --dont-cover-languages, --dont-cover-language, --dont-cover
Possible choices: c, c++, fortran, R, julia, matlab, python, cmake, make, lpy, osr, pytorch, sbml, dummy, executable, mpi, timesync
Language(s) to ignore in coverage.
- --filename
File to save coveragerc to
- --setup-cfg
setup.cfg file containing coverage options
fconvert¶
Convert a file of one type into another compatible type.
yggdrasil fconvert [-h] [--from SRC_TYPE] [--to DST_TYPE]
[--src-kwargs SRC_KWARGS] [--dst-kwargs DST_KWARGS]
[--transform TRANSFORM]
src dst
Positional Arguments¶
- src
Name of file to convert
- dst
Name of destination file
Named Arguments¶
- --from, --src-type
Source file type
- --to, --dst-type
Destination file type
- --src-kwargs
Keyword arguments for source file communicator in JSON format
- --dst-kwargs
Keyword arguments for destination file communicator in JSON format
- --transform
Transform keyword arguments for transforming messages between source and destination in JSON format
yggcc
Command¶
Alias for yggdrasil compile-model
yggccflags
Command¶
usage: yggccflags [-h] [--cpp] [--toolname TOOLNAME] [--disable-python-c-api]
[--with-asan]
Named Arguments¶
- --cpp
Get the compilation flags used for C++ programs.
Default: False
- --toolname
Name of the tool that associated flags be returned for.
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
yggcctool
Command¶
usage: yggcctool [-h] [--cpp] [--fullpath]
Named Arguments¶
- --cpp
Get the compiler used for C++ programs.
Default: False
- --fullpath
Get the full path to the tool exectuable.
Default: False
yggclean
Command¶
Alias for yggdrasil clean
yggcompile
Command¶
Alias for yggdrasil compile
yggconfig
Command¶
Alias for yggdrasil config
yggdevup
Command¶
Alias for yggdrasil dev-update
ygggha
Command¶
Alias for yggdrasil gha
ygginfo
Command¶
Alias for yggdrasil info
ygginstall
Command¶
Alias for yggdrasil install
yggldflags
Command¶
usage: yggldflags [-h] [--cpp] [--toolname TOOLNAME] [--disable-python-c-api]
[--with-asan]
Named Arguments¶
- --cpp
Get the compilation flags used for C++ programs.
Default: False
- --toolname
Name of the tool that associated flags be returned for.
- --disable-python-c-api
Disable access to the Python C API from yggdrasil.
Default: False
- --with-asan
Compile with Clang ASAN if available.
Default: False
yggldtool
Command¶
usage: yggldtool [-h] [--cpp] [--fullpath]
Named Arguments¶
- --cpp
Get the linker used for C++ programs.
Default: False
- --fullpath
Get the full path to the tool exectuable.
Default: False
yggmodelform
Command¶
Alias for yggdrasil model-form-schema
yggrun
Command¶
Alias for yggdrasil run
yggschema
Command¶
Alias for yggdrasil schema
yggvalidate
Command¶
Alias for yggdrasil validate