Python库 | dojo-cli-0.1.5.tar.gz

# dojo-cli A command-line interface library for black box domain model execution. This library enables users to execute domain models locally. The library has 7 key methods: - List the latest versions of all available models. - Print parameter metadata for a selected model. - Print a summary of the output and accessory files of a selected model. - Print a desription of a selected model. - Get the results of a detached model run that has finished. - Run a model. - List all versions of a model. ## Installation Ensure you have a working installation of [Docker](https://docs.docker.com/engine/install/). Once Docker is installed on Linux or Mac you can add the current user to the Docker group with: ``` sudo groupadd docker sudo gpasswd -a $USER docker ``` then log out/back in so changes can take effect. This should be done after installing Docker. Dojo-cli can be installed via `pip`: ``` pip install dojo-cli ``` ## Demo script A text file demonstrating the commands for dojo-cli installation and use is located at [/docs/demo_script.txt](/docs/demo_script.txt). ## Running models attached vs. detached By default the `runmodel` command runs the model attached, which means **dojo** waits for processing to finish before returning control to the command line. For models that take a long time to process, the `--attached=False` parameter can be used with [runmodel](#runmodel) to run the model in background, and [results](#results) used to check for model run completion. ## Setup The CLI requires a configuration file with [DOJO API](https://github.com/dojo-modeling) credentials. This filename can be passed with each CLI command via the `--config` option, or the default file *.config* will be used. See *example.config* for guidance: ``` { "DOJO_URL": "https://dojo-test.com", "DOJO_USER": "", "DOJO_PWD": "" } ``` If running the library locally from source, the following libraries are required to be installed: ``` Click>=7.0,<8 docker>=5.0.3 Jinja2>=2.11.3 ``` ## CLI help The following commands will provide details of each available dojo command: ``` dojo --help dojo describe --help dojo listmodels --help dojo outputs --help dojo parameters --help dojo results --help dojo runmodel --help dojo versions --help ``` ## Available commands - [describe](#describe): Print a description of the model. - [listmodels](#listmodels): List available models. - [outputs](#outputs): Print descriptions of the output and accessory files produced by a model. - [parameters](#parameters): Print the parameters required to run a model. - [results](#results): Get the results of a model finished running detached. - [runmodel](#runmodel): Run a model. - [versions](#versions): List all versions of a model. ## *describe* Print a description of the model. ### Parameters - `--model` : name of the model - `--config` : name of configuation file; defaults to *.config* - `--version` : version of the model if `--model` is not passed ### Example `dojo describe --model="Population Model"` ``` NAME ---- Population Model MODEL FAMILY ------------ Kimetrica DESCRIPTION ----------- The population model serves as an ancillary tool to distribute, disaggregate yearly population projections onto a geospatial representation. Occasionally, the output of this model is required as an independent variable for downstream models.y ... ``` ## *listmodels* ### Description List available models. ### Parameters - `--config` : name of configuation file; defaults to *.config* ### Example $ `dojo listmodels` ``` (1) APSIM (2) APSIM-Cropping (3) APSIM-Rangelands (4) Accessibility Model (5) AgMIP Seasonal Crop Emulator (6) CHIRPS - Climate Hazards Center Infrared Precipitation with Stations (7) CHIRPS-GEFS (8) CHIRPS-GEFS Monthly (9) CHIRPS-Monthly ... ``` ## *outputs* ### Description Prints a summary of the output and accessory files produced by a model. ### Parameters - `--model` : name of the model - `--config` : name of configuation file; defaults to *.config* - `--version` : version of the model if `--model` is not passed ### Example `dojo outputs --model=Topoflow` ``` Getting output file information for Topoflow ... Topoflow writes 4 output file(s): (1) Test1_2D-d-flood.nc: Land Surface Water Depth in netcdf format with the following labeled data: Y: Y X: longitude datetime: Datetime d_flood: Land Surface Water Depth (2) Test1_2D-Q.nc: Volumetric Discharge in netcdf format with the following labeled data: Y: Y X: longitude datetime: Datetime Q: Volumetric Discharge [m^3/s] (3) Test1_2D-d.nc: Max Channel Flow Depth in netcdf format with the following labeled data: Y: Y X: longitude datetime: Datetime d: Max Channel Flow Depth (4) Test1_2D-u.nc: Mean Channel Flow Velocity in netcdf format with the following labeled data: Y: Y X: longitude datetime: Datetime u: Mean Channel Flow Velocity "Topoflow" version 2ddd2cbe-364b-4520-a28e-a5691227db39 writes 8 accessory file(s): (1) Test1_0D-Q.png (2) Test1_0D-d-flood.png (3) Test1_0D-d.png (4) Test1_0D-u.png (5) Test1_2D-Q.mp4 (6) Test1_2D-d-flood.mp4 (7) Test1_2D-d.mp4 (8) Test1_2D-u.mp4 ``` ## *parameters* ### Description Prints a description of model parameters and writes an example to file. ### Parameters - `--model` : name of the model - `--config` : name of configuation file; defaults to *.config* - `--version` : version of the model if `--model` is not passed ### Example `dojo parameters --model=CHIRPS-Monthly` ``` Getting parameters for CHIRPS-Monthly ... Model run parameters for CHIRPS-Monthly: Parameter 1 : month Description : 2-digit month Type : int Unit : month Unit Description: month Parameter 2 : year Description : 4-digit year Type : int Unit : years Unit Description: years Parameter 3 : bounding box Description : geographical bounding box of x,y min/max values. format: [ [xmin, ymin], [xmax, ymax] ] example: [[33.512234, 2.719907], [49.98171,16.501768]] Type : float Unit : longitude, latitude values Unit Description: longitude, latitude values Example parameters: month: 01 year: 2021 bounding_box: '[[33.512234, 2.719907], [49.98171,16.501768]]' Template CHIRPS-Monthly parameters file written to params_template.json. ``` Additionally, `parameters` will write *params_template.json* with example model parameters: ``` { "month": 1, "year": 2021, "bounding_box": "[[33.512234, 2.719907], [49.98171,16.501768]]" } ``` ## *results* ### Description This command is used for models that have been run **detached** e.g. `dojo runmodel -model="mymodel" --attached=False`. Normally, models that take a long time to run are executed detached. The *results* command will check whether the model run has completed, and if so, copy the output and logs to the local output folder. ### Parameters - `--id` : id of the docker container - `--name` : name of the docker container - `--config` : name of configuation file; defaults to *.config* One of either `--id` or `--name` is required. When you run a model, the name of the model Docker container will be displayed e.g. ``` Running Stochastic Gridded Conflict Model version 33cf1a60-2544-420f-ae08-b453a9751cfc in Docker container dojo-stochasticgriddedconflictmodel20211227133418 ``` The model run Docker container id and name will also be listed in the file `run-info.txt` in the local output folder (see the *runmodel* section below for information regarding the output directory structure). The model run Docker container id and name can also be found by the command `docker ps -a`. Docker containers created by `dojo --runmodel` will have the `dojo-` prefix, followed by the model name and a datetime stamp. ### Examples ```dojo results --name=dojo-mymodel20211225133418``` If the model is still running in the container, the above command will produce the following output: ``` Results for mymodel