Command Line Interface (CLI) Overview
QBlade-EE
This feature is only available in the Enterprise Edition of QBlade.
QBlade-EE can also be executed in a command line interface (CLI). The main purpose of QBlade’s CLI is to batch-process large sets of simulations in parallel while reducing any computational overhead from the GUI. When processing large sets of simulations a single instance of QBlade will act as the thread manager, in charge of creating new QBlade instances for each simulation that is evaluated and queuing these simulations over all available threads. This approach has the advantage of being highly robust, as if one simulation crashes for any reason it wont affect any other simulation and the batch run will still complete without the need for user intervention. This section details the functionality of the QBlade CLI and its options.
To start QBlade in CLI mode simply call QBlade’s executable from the command line while adding the parameter -cli to indicate that instead of starting QBlade in GUI mode it will be operated in CLI mode.
QBladeEE -cli
If the command above is executed, QBlade prints out the following information on the screen:
!!!!! Welcome to QBlade EE v2.0.5.1_alpha windows Command Line Interface (CLI) !!!!!
*************************************** OpenCL *********************************************
Available OpenCL Devices:
-d0 : to use CPU: OpenMp (default)
-d1 : to use GPU: OpenCL 2.0 AMD-APP (3380.6) gfx1030
-d2 : to use GPU: OpenCL 3.0 NEO Intel(R) UHD Graphics 770
Specify the OpenCL device by passing -dXX to the CLI, where -d0 is the default
Specify the OpenCL group size by passing -gXX to the CLI, where -g32 is the default
--------------------------------------------------------------------------------------------
************************************ Multi Threading ***************************************
Available CPU Cores:
- CPU cores found: 20
Set the parallel threads by passing -tXX to the CLI, where -t1 is the default
--------------------------------------------------------------------------------------------
Missing arguments - type 'QBlade -cli help' for a list of options!
Since no options have been passed in this example of executing the CLI, the program is exiting without any actions. However, some useful information has already been printed on screen. This includes the OpenCL Devices as they have been detected by QBlade and the total number of CPU Cores that could be found on the machine. This information is useful when evaluating large sets of simulations to inform QBlade which OpenCL device to use and how many simulations should be evaluated in parallel.
The available functionality of the QBlade CLI can be viewed by adding help (note that the minus sign is not required when adding the help command, while it is mandatory when adding -cli).
QBladeEE -cli help
This command prints out an overview of all CLI functionality:
**************************************** Help **********************************************
!! CLI options can be given in any order !!
!! Multiple files and/or directories can be specified with a single CLI call!!
!! All directories must be input as an ABSOLUTE path !!
List of CLI Options:
General
--------------------------------------------------
help - show this help message
Compute & Parallelization
--------------------------------------------------
-dX - select compute device X for wake calculations
-gX - set OpenCL group size X for wake calculations
-tX - number of parallel simulation threads (batch level)
-oX - number of OpenMP threads per simulation thread
Input Files & Working Directories
--------------------------------------------------
\directory\simulation.sim - evaluate a .sim file and save result as *.qpr1
\directory\project.qpr - evaluate a .qpr project and save it as .qpr1
\directory - add a WORKING_DIR (can be specified multiple times)
Batch Execution Modes
--------------------------------------------------
all_sim - batch evaluate all .sim files in all WORKING_DIR(s) and saves them as *.qpr1
all_qpr - batch evaluate all .qpr files in all WORKING_DIR(s) and save them as *.qpr1
skip - skip evaluation of .qpr and .sim files if a .qpr1 file exists or .sim files that were already exported
Storage & Cleanup Behavior
--------------------------------------------------
no_save - do not store simulations after evaluation
remove_wind - delete windfield (.bts) after simulation (.sim) is evaluated
Post-Processing & Export Control
--------------------------------------------------
exp_h2bin - export results in HAWC2 binary format
exp_h2ascii - export results in HAWC2 ASCII format (if no HAWC2 binary export)
exp_ascii - export results in generic ASCII format
exp_fastbin - export results in FAST binary format
exp_modal - export modal frequencies (if modal analysis was run)
exp_sim - export the 'simulation time graph' data
exp_cut_txt - export cut-planes in TXT format
exp_cut_vtu - export cut-planes in VTU format
post_exp - export results from all finished .qpr / .qpr1 files in all WORKING_DIR(s)
exp=\directory - set export directory for results and DLC tables
flt=\directory\filter.* - apply filter file for auto- and post-export
dlc=\directory\dlc.* - generate simulations from DLC table (requires WORKING_DIR, or export diretory)
Output & Logging
--------------------------------------------------
-vX - number of rows shown in live batch view (default: 40)
echo_off - disable verbose console output
Command Line (CLI) Functionality
In this section the different CLI options are briefly explained.
-dThis parameter is used to specify on which OpenCL device QBlade should be executed. The default value is 0. To execute on the OpenCL device 1, the parameter would be
-d1.-gThis parameter specifies the OpenCL work-group size, which has a GPU dependent impact on the OpenCL performance. The work-group size should always be a power of 2. The default value is 32. To specify a work-group size of 64 you would pass the parameter
-g64.-tThis parameter sets how many parallel instances of QBlade should be started when evaluating a batch of simulations. The default values is 1. To specify 12 parallel threads you would pass the parameter
-t12.-oThis parameter sets how many openMp threads should be used for each parallel instance of QB. This is specifically important to fine tune the performance of QB instances in a cloud-computing environment.
c:directorysimulation.simPassing the absolute location of a Simulation Definition ASCII File (*.sim) as one of the parameters adds this simulation definition to the list of simulations that will be evaluated. Multiple simulation definitions may be added during a single CLI call. Finished simulation definitions are stored as .qpr1, to indicate that these are project files that have already been evaluated. Should a simulation fail for any reason the associated project is stored as *.qpre instead, to indicate that this is a problematic simulation.
c:directoryproject.qprPassing the absolute location of a QBlade Project File (*.qpr) adds all simulation definitions within this project to the list of simulations that will be evaluated. Multiple project files may be added during a single CLI call. Finished project files are stored as *.qpr1, to indicate that these are project files that have already been evaluated. Should a simulation fail for any reason the associated project is stored as *.qpre instead, to indicate that this is a problematic simulation.
c:directoryPassing the absolute path of any directory adds this directory to the list of working directories (WORKING_DIR). Multiple directories may be added during a single CLI call.
all_simAdding the parameter
all_simcauses QBlade to add all *.sim files from all WORKING_DIR(s) to the list of simulations that will be evaluated.all_qprAdding the parameter
all_qprcauses QBlade to add all *.qpr files from to all WORKING_DIR(s) to the list of projects that will be evaluated.no_saveThe parameter
no_saveprevents QBlade from automatically storing finished simulations as *.qpr1 or *.qpr2 files. Sometimes those files are not explicitly needed, for example if results are automatically exported and the user wants to reduce disk memory consumption during very large batch runs.remove_windThe parameter
remove_windremoves the binary windfield files (*.bts), that may be automatically generated when a simulation definition file (*.sim) is evaluated. This can be useful to reduce disk memory usage during very large batch runs.skipAdding the parameter
skipcauses QBlade to skip the evaluation of a simulation (*.sim) or project (*.qpr) file if an assocated finished project file (*.qpr1) already exists, or if the results from this simulation have already been exported previously. When using skip during post_exp files are only exported if their filename does not exist yet.exp_h2binThe parameter
exp_h2binadds the HAWC2 binary format to the list of export formats. Whenever a simulation is completed the results of this simulation will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.exp_h2asciiThe parameter
exp_h2asciiadds the HAWC2 ASCII format to the list of export formats. Whenever a simulation is completed the results of this simulation will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.exp_asciiThe parameter
exp_asciiadds the ASCII format to the list of export formats. Whenever a simulation is completed the results of this simulation will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.exp_fastbinThe parameter :code:èxp_fastbin`adds the OpenFAST binary format (.outb) to the list of export formats. Whenever a simulation is completed the results of this simulation will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.
exp_modalThe parameter
exp_modalexports modal frequencies during auto_exp and post_exp exports. The modal frequencies are only exported if the simulation contains the results of a modal analysis. The exported modal frequencies are stored in a file with the appendix _modal.txt.exp_simThe parameter
exp_simexports the simulation time graph data during auto_exp and post_exp exports. The sim time data is only exported if the simulation stores these results. The exported simulation time data is stored in a file with the appendix _SimTimeData in the filename.exp_cut_txtThe parameter
exp_cut_txtadds the cut-plane TXT format to the list of export formats. Whenever a cut-plane is evaluated, its velocity field will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.exp_cut_vtuThe parameter
exp_cut_vtuadds the cut-plane VTU format to the list of export formats. Whenever a cut-plane is evaluated, its velocity field will be automatically exported for all specified formats. As default no format is specified, so auto-export if disabled.post_expThe parameter
post_expcauses QBlade to automatically export the results from all finished project files (*.qpr, *.qpr1, *.qpr2) in all WORKING_DIR(s). This parameter only affects simulations that are already finished when the CLI call is executed and not simulations that are being evaluated during the CLI call. Simulations are exported in all formats that have been added to the export format list.exp=\directoryThis sets the export directory for results and DLC tables generation
dlc=\directory\dlc.*This call allows to create simulations from a dlc table definition. It requires the filename of the dlc definition. Furthermore, a WORKING_DIR in which the simulations are created is required.
flt=\directory\filter.*This sets a filter file that is applied during the generation of all auto-export and post-export files, see Global Export Filter.
Sample CLI Call to Start a Batch Run
The following call is an example for a CLI call of QBlade to evaluate and automatically export a batch of simulation definition files located in the folder c:\simulations\.
QBladeEE -cli -d1 -g64 -t12 c:\simulations all_sim exp_h2bin remove_wind skip
After this CLI call QBlade will evaluate all simulation definitions (all_sim) located in c:\simulations\ over 12 parallel threads (-t12). OpenCL device 1 will be used (-d1) with a work-group size of 64 (-g64). The simulation results will automatically be exported to the HAWC2 binary format (exp_h2bin). Simulations that have already been evaluated previously will be skipped (skip) and the automatically generated binary wind fields will be removed after a simulation is finished (remove_wind). After executing this call the following info is printed out on the screen:
!!!!! Welcome to QBlade EE v2.0.5.1_alpha windows Command Line Interface (CLI) !!!!!
*************************************** OpenCL *********************************************
Available OpenCL Devices:
-d0 : to use CPU: OpenMp (default)
-d1 : to use GPU: OpenCL 1.2 CUDA Quadro P6000
Specify the OpenCL device by passing -dXX to the CLI, where -d0 is the default
Specify the OpenCL group size by passing -gXX to the CLI, where -g32 is the default
--------------------------------------------------------------------------------------------
************************************ Multi Threading ***************************************
Available CPU Cores:
- CPU cores found: 16
Set the parallel threads by passing -tXX to the CLI, where -t1 is the default
--------------------------------------------------------------------------------------------
************************************ Input User Commands ***********************************
1 - OpenCl device: 1
2 - OpenCl groupsize: 64
3 - Parallel Threads: 12
4 - all_sim batch evaluate all .sim files in all WORKING_DIR(s) and saves them as .qpr1
5 - WORKING_DIR 0: c:\simulations
6 - exp_h2bin adds HAWC2BINARY format to auto-export and post-export formats
7 - remove_wind removes bts windfields after auto-generation through .sim files
8 - skip skip evauation of .qpr files if a .qpr1 file exists; .sim files that were already exported; cut-planes if a .qpr2 exists
Using OpenCL on GPU: OpenCL 1.2 CUDA Quadro P6000
--------------------------------------------------------------------------------------------
************************* List of sim files that will be evaluated *************************
[1] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y-20.sim
[2] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y0.sim
[3] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y20.sim
[4] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y-20.sim
[5] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y0.sim
[6] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y20.sim
[7] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y-20.sim
[8] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y0.sim
[9] c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y20.sim
[10] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y-20.sim
[11] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y0.sim
[12] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y20.sim
[13] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis0_i0_y-20.sim
[14] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis0_i0_y0.sim
[15] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis0_i0_y20.sim
[16] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis30_i0_y-20.sim
[17] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis30_i0_y0.sim
[18] c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis30_i0_y20.sim
--------------------------------------------------------------------------------------------
****************************** Simulation of sim definitions *******************************
...queuing 18 simulations over 12 threads!
...starting evaluation of < Queue Item 1/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y-20.sim ; with ThreadID 0x36e4 at 16:15:59 ; on 10.01.2023
...starting evaluation of < Queue Item 2/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y0.sim ; with ThreadID 0x1134 at 16:16:00 ; on 10.01.2023
...starting evaluation of < Queue Item 3/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis-30_i0_y20.sim ; with ThreadID 0x3fc4 at 16:16:01 ; on 10.01.2023
...starting evaluation of < Queue Item 4/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y-20.sim ; with ThreadID 0x4094 at 16:16:02 ; on 10.01.2023
...starting evaluation of < Queue Item 5/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y0.sim ; with ThreadID 0x11c4 at 16:16:03 ; on 10.01.2023
...starting evaluation of < Queue Item 6/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis0_i0_y20.sim ; with ThreadID 0x3e10 at 16:16:03 ; on 10.01.2023
...starting evaluation of < Queue Item 7/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y-20.sim ; with ThreadID 0x2d00 at 16:16:04 ; on 10.01.2023
...starting evaluation of < Queue Item 8/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y0.sim ; with ThreadID 0x3090 at 16:16:05 ; on 10.01.2023
...starting evaluation of < Queue Item 9/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10000_ws31_hs11_tp15_mis30_i0_y20.sim ; with ThreadID 0x3360 at 16:16:06 ; on 10.01.2023
...starting evaluation of < Queue Item 10/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y-20.sim ; with ThreadID 0x1cbc at 16:16:07 ; on 10.01.2023
...starting evaluation of < Queue Item 11/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y0.sim ; with ThreadID 0xdfc at 16:17:17 ; on 10.01.2023
...starting evaluation of < Queue Item 12/18 > : c:\simulations\QB_HEXAFLOAT_LC63_s10001_ws31_hs11_tp15_mis-30_i0_y20.sim ; with ThreadID 0x2f54 at 16:17:17 ; on 10.01.2023
As can be seen from QBlade’s console output an overview of the passed options is given, followed by an overview of the queued simulations before the evaluation of the simulations themselves starts. The information on the screen will now be updated whenever a simulation instance is finished and a new simulation instance is started to reflect on the progression of the batch run. After all simulations have been evaluated and exported QBlade will close and return to the command window.