From 3f3b91662b6774ce5e8a5760bde4e9fca47ad94c Mon Sep 17 00:00:00 2001 From: lherrero Date: Wed, 28 Aug 2024 14:06:59 +0200 Subject: [PATCH] EXPID consistent (maybe) and help messages updated #1399 --- docs/source/userguide/configure/index.rst | 43 ++-- docs/source/userguide/create/index.rst | 10 +- docs/source/userguide/manage/index.rst | 213 ++++++++++++----- .../userguide/modifying_workflow/index.rst | 46 ++-- .../userguide/monitor_and_check/index.rst | 218 ++++++++++-------- docs/source/userguide/run/index.rst | 41 ++-- docs/source/userguide/wrappers/index.rst | 6 +- 7 files changed, 362 insertions(+), 215 deletions(-) diff --git a/docs/source/userguide/configure/index.rst b/docs/source/userguide/configure/index.rst index 360d7a959..81f0abf43 100644 --- a/docs/source/userguide/configure/index.rst +++ b/docs/source/userguide/configure/index.rst @@ -40,24 +40,33 @@ Experiment workflow, which contains all the jobs and its dependencies, will be s Options: :: - - usage: autosubmit create [-group_by {date,member,chunk,split} -expand -expand_status] [-h] [-np] [-cw] expid - - expid experiment identifier - - -h, --help show this help message and exit - -np, --noplot omit plot creation - --hide, hide the plot + usage: autosubmit create [-h] [-np] [--hide] [-d] [-o {pdf,png,ps,svg}] [-group_by {date,member,chunk,split,automatic}] + [-expand EXPAND] [-expand_status EXPAND_STATUS] [-nt] [-cw] [-v] [-p] [-f] + EXPID + + create specified experiment joblist + + positional arguments: + EXPID experiment identifier + + options: + -h, --help show this help message and exit + -np, --noplot omit plot + --hide hides plot window + -d, --detail Show Job List view in terminal + -o {pdf,png,ps,svg}, --output {pdf,png,ps,svg} + chooses type of output for generated plot -group_by {date,member,chunk,split,automatic} - criteria to use for grouping jobs - -expand, list of dates/members/chunks to expand - -expand_status, status(es) to expand - -nt --notransitive - prevents doing the transitive reduction when plotting the workflow - -cw --check_wrapper - Generate the wrapper in the current workflow - -d --detail - Shows Job List view in terminal + Groups the jobs automatically or by date, member, chunk or split + -expand EXPAND Supply the list of dates/members/chunks to filter the list of jobs. Default = "Any". LIST = "[ + 19601101 [ fc0 [1 2 3 4] fc1 [1] ] 19651101 [ fc0 [16-30] ] ]" + -expand_status EXPAND_STATUS + Select the statuses to be expanded + -nt, --notransitive Disable transitive reduction + -cw, --check_wrapper Generate possible wrapper in the current workflow + -v, --update_version Update experiment version + -p, --profile Prints performance parameters of the execution of this command. + -f, --force force regenerate job_list Example: :: diff --git a/docs/source/userguide/create/index.rst b/docs/source/userguide/create/index.rst index fc9f11584..d11eea351 100644 --- a/docs/source/userguide/create/index.rst +++ b/docs/source/userguide/create/index.rst @@ -194,11 +194,14 @@ To test the experiment, use the command: Options: :: + usage: autosubmit test [-h] -c CHUNKS [-m MEMBER] [-s STARDATE] [-H HPC] [-b BRANCH] [-v] EXPID - usage: autosubmit test [-h] -c CHUNKS [-m MEMBER] [-s STARDATE] [-H HPC] [-b BRANCH] expid + test experiment - expid experiment identifier + positional arguments: + EXPID experiment identifier + options: -h, --help show this help message and exit -c CHUNKS, --chunks CHUNKS chunks to run @@ -208,7 +211,8 @@ Options: stardate to run -H HPC, --HPC HPC HPC to run experiment on it -b BRANCH, --branch BRANCH - branch from git to run (or revision from subversion) + branch of git to run (or revision from subversion) + -v, --update_version Update experiment version Example: :: diff --git a/docs/source/userguide/manage/index.rst b/docs/source/userguide/manage/index.rst index 59e9eb04e..3ed135256 100644 --- a/docs/source/userguide/manage/index.rst +++ b/docs/source/userguide/manage/index.rst @@ -16,14 +16,20 @@ You must execute: Options: :: - usage: autosubmit clean [-h] [-pr] [-p] [-s] expid + usage: autosubmit clean [-h] [-pr] [-p] [-s] [-v] EXPID - expid experiment identifier + clean specified experiment + + positional arguments: + EXPID experiment identifier + + options: + -h, --help show this help message and exit + -pr, --project clean project + -p, --plot clean plot, only 2 last will remain + -s, --stats clean stats, only last will remain + -v, --update_version Update experiment version - -h, --help show this help message and exit - -pr, --project clean project - -p, --plot clean plot, only 2 last will remain - -s, --stats clean stats, only last will remain * The -p and -s flag are used to clean our experiment ``plot`` folder to save disk space. Only the two latest plots will be kept. Older plots will be removed. @@ -59,12 +65,24 @@ use, unless it is unarchived. .. code-block:: - autosubmit archive + autosubmit archive EXPID Options: +:: + usage: autosubmit archive [-h] [-nclean] [-uc] [-v] [--rocrate] EXPID + + archives an experiment + + positional arguments: + EXPID experiment identifier + + options: + -h, --help show this help message and exit + -nclean, --noclean Avoid Cleaning of experiment folder + -uc, --uncompress Only does a container without compress + -v, --update_version Update experiment version + --rocrate Produce an RO-Crate file -.. runcmd:: autosubmit archive -h - :caption: ``autosubmit archive`` options The archived experiment will be stored as a ``tar.gz` file, under a directory named after the year of the last ``_COMPLETED`` file @@ -79,12 +97,24 @@ To unarchive an experiment, use the command: .. code-block:: - autosubmit unarchive + autosubmit unarchive EXPID Options: +:: + usage: autosubmit unarchive [-h] [-nclean] [-uc] [-v] [--rocrate] EXPID + + unarchives an experiment + + positional arguments: + EXPID experiment identifier + + options: + -h, --help show this help message and exit + -nclean, --noclean Avoid Cleaning of experiment folder + -uc, --uncompressed Untar an uncompressed tar + -v, --update_version Update experiment version + --rocrate Unarchive an RO-Crate file -.. runcmd:: autosubmit unarchive -h - :caption: ``autosubmit unarchive`` options How to delete the experiment ---------------------------- @@ -101,13 +131,18 @@ To delete the experiment, use the command: Options: :: + usage: autosubmit delete [-h] [-f] [-v] EXPID - usage: autosubmit delete [-h] [-f] expid + delete specified experiment - expid experiment identifier + positional arguments: + EXPID experiment identifier + options: -h, --help show this help message and exit - -f, --force deletes experiment without confirmation + -f, --force deletes experiment without confirmation + -v, --update_version Update experiment version + Example: @@ -121,6 +156,27 @@ How to migrate an experiment ---------------------------- The Autosubmit Migrate command is used to migrate data from one user to another. +:: + autosubmit migrate EXPID + +Options: +:: + usage: autosubmit migrate [-h] [-o] [-p] [-r] [-v] [-fs {Any,READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN}] EXPID + + Migrate experiments from current user to another + + positional arguments: + EXPID experiment identifier + + options: + -h, --help show this help message and exit + -o, --offer Offer experiment + -p, --pickup Pick-up released experiment + -r, --onlyremote Only moves remote files + -v, --update_version Update experiment version + -fs {Any,READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN}, --filter_status {Any,READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN} + Select the original status to filter the list of jobs + To migrate it, you need to generate a new file inside $expid/conf/ with the **new user** information for each platform that you want to migrate. @@ -164,14 +220,14 @@ Migrate file example: $expid/conf/migrate.yml User A, To offer the experiment: :: - autosubmit migrate --offer expid + autosubmit migrate --offer EXPID Local files will be archived and remote files put in the HPC temporary directory. User A To only offer the remote files :: - autosubmit migrate expid --offer --onlyremote + autosubmit migrate EXPID --offer --onlyremote Only remote files will be put in the HPC temporary directory. @@ -184,14 +240,14 @@ Only remote files will be put in the HPC temporary directory. Now to pick the experiment, the user B, must do :: - autosubmit migrate --pickup expid + autosubmit migrate --pickup EXPID Local files will be unarchived and remote files copied from the temporal location. To only pick the remote files, the user B, must do :: - autosubmit migrate --pickup expid --onlyremote + autosubmit migrate --pickup EXPID --onlyremote How to refresh the experiment project ------------------------------------- @@ -211,14 +267,19 @@ It checks experiment configuration and copy code from original repository to pro Options: :: + usage: autosubmit refresh [-h] [-mc] [-jc] [-v] EXPID - usage: autosubmit refresh [-h] expid + refresh project directory for an experiment - expid experiment identifier + positional arguments: + EXPID experiment identifier + options: -h, --help show this help message and exit -mc, --model_conf overwrite model conf file -jc, --jobs_conf overwrite jobs conf file + -v, --update_version Update experiment version + Example: :: @@ -239,6 +300,21 @@ Use the command: *DESCRIPTION* is the new description of your experiment. +Options: +:: + usage: autosubmit updatedescrip [-h] [-v] EXPID DESCRIPTION + + Updates the experiment's description. + + positional arguments: + EXPID experiment identifier + DESCRIPTION New description. + + options: + -h, --help show this help message and exit + -v, --update_version Update experiment version + + Autosubmit will validate the provided data and print the results in the command line. Example: @@ -268,43 +344,56 @@ You must execute: Options: :: - usage: autosubmit setstatus [-h] [-np] [-s] [-t] [-o {pdf,png,ps,svg}] [-fl] [-fc] [-fs] [-ft] [-group_by {date,member,chunk,split} -expand -expand_status] [-cw] expid - - expid experiment identifier - - -h, --help show this help message and exit - -o {pdf,png,ps,svg}, --output {pdf,png,ps,svg} - type of output for generated plot - -np, --noplot omit plot - -s, --save Save changes to disk - -t, --status_final Target status - -fl FILTER_LIST, --list - List of job names to be changed - -fc FILTER_CHUNK, --filter_chunk - List of chunks to be changed - -fs FILTER_STATUS, --filter_status - List of status to be changed - -ft FILTER_TYPE, --filter_type - List of types to be changed - -ftc FILTER_TYPE_CHUNK --filter_type_chunk - Accepts a string with the formula: "[ 19601101 [ fc0 [1 2 3 4] Any [1] ] 19651101 [ fc0 [16 30] ] ],SIM,SIM2" - Where SIM, SIM2 are section (job types) names that also accept the keyword "Any" so the changes apply to all sections. - Starting Date (19601101) does not accept the keyword "Any", so you must specify the starting dates to be changed. - You can also specify date ranges to apply the change to a range on dates. - Member names (fc0) accept the keyword "Any", so the chunks ([1 2 3 4]) given will be updated for all members. - Chunks must be in the format "[1 2 3 4]" where "1 2 3 4" represent the numbers of the chunks in the member, - no range format is allowed. - -d When using the option -ftc and sending this flag, a tree view of the experiment with markers indicating which jobs - have been changed will be generated. - --hide, hide the plot - -group_by {date,member,chunk,split,automatic} - criteria to use for grouping jobs - -expand, list of dates/members/chunks to expand - -expand_status, status(es) to expand - -nt --notransitive - prevents doing the transitive reduction when plotting the workflow - -cw --check_wrapper - Generate the wrapper in the current workflow + usage: autosubmit setstatus [-h] [-np] [-s] -t {READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN,QUEUING,RUNNING,HELD} [-v] + (-fl LIST | -fc FILTER_CHUNKS | -fs FILTER_STATUS | -ft FILTER_TYPE | -ftc FILTER_TYPE_CHUNK | -ftcs FILTER_TYPE_CHUNK_SPLIT) + [--hide] [-group_by {date,member,chunk,split,automatic}] [-expand EXPAND] + [-expand_status EXPAND_STATUS] [-nt] [-cw] [-d] + expid + + sets job status for an experiment + + positional arguments: + expid experiment identifier + + options: + -h, --help show this help message and exit + -np, --noplot omit plot + -s, --save Save changes to disk + -t {READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN,QUEUING,RUNNING,HELD}, --status_final {READY,COMPLETED,WAITING,SUSPENDED,FAILED,UNKNOWN,QUEUING,RUNNING,HELD} + Supply the target status + -v, --update_version Update experiment version + -fl LIST, --list LIST + Supply the list of job names to be changed. Default = "Any". LIST = "b037_20101101_fc3_21_sim + b037_20111101_fc4_26_sim" + -fc FILTER_CHUNKS, --filter_chunks FILTER_CHUNKS + Supply the list of chunks to change the status. Default = "Any". LIST = "[ 19601101 [ fc0 [1 2 3 4] + fc1 [1] ] 19651101 [ fc0 [16-30] ] ]" + -fs FILTER_STATUS, --filter_status FILTER_STATUS + Select the status (one or more) to filter the list of jobs.Valid values = ['Any', 'READY', + 'COMPLETED', 'WAITING', 'SUSPENDED', 'FAILED', 'UNKNOWN'] + -ft FILTER_TYPE, --filter_type FILTER_TYPE + Select the job type to filter the list of jobs + -ftc FILTER_TYPE_CHUNK, --filter_type_chunk FILTER_TYPE_CHUNK + Supply the list of chunks to change the status. Default = "Any". When the member name "all" is set, + all the chunks selected from for that member will be updated for all the members. Example: all [1], + will have as a result that the chunks 1 for all the members will be updated. Follow the format: "[ + 19601101 [ fc0 [1 2 3 4] Any [1] ] 19651101 [ fc0 [16-30] ] ],SIM,SIM2,SIM3" + -ftcs FILTER_TYPE_CHUNK_SPLIT, --filter_type_chunk_split FILTER_TYPE_CHUNK_SPLIT + Supply the list of chunks & splits to change the status. Default = "Any". When the member name "all" + is set, all the chunks selected from for that member will be updated for all the members. Example: + all [1], will have as a result that the chunks 1 for all the members will be updated. Follow the + format: "[ 19601101 [ fc0 [1 [1 2] 2 3 4] Any [1] ] 19651101 [ fc0 [16-30] ] ],SIM,SIM2,SIM3" + --hide hides plot window + -group_by {date,member,chunk,split,automatic} + Groups the jobs automatically or by date, member, chunk or split + -expand EXPAND Supply the list of dates/members/chunks to filter the list of jobs. Default = "Any". LIST = "[ + 19601101 [ fc0 [1 2 3 4] fc1 [1] ] 19651101 [ fc0 [16-30] ] ]" + -expand_status EXPAND_STATUS + Select the statuses to be expanded + -nt, --notransitive Disable transitive reduction + -cw, --check_wrapper Generate possible wrapper in the current workflow + -d, --detail Generate detailed view of changes + Examples: :: @@ -397,10 +486,10 @@ How to change the job status without stopping autosubmit This procedure allows you to modify the status of your jobs without having to stop Autosubmit. -You must create a file in ``//pkl/`` named: +You must create a file in ``//pkl/`` named: :: - updated_list_.txt + updated_list_.txt Format: @@ -425,11 +514,11 @@ If Autosubmit finds the above file, it will process it. You can check that the p if you see that the file name has changed to: :: - update_list___