pelayout is a script in CIMEROOT/scripts/Tools.

$ ./pelayout --help
usage: pelayout [-h] [-d] [-v] [-s] [--set-ntasks SET_NTASKS]
                [--set-nthrds SET_NTHRDS] [--format FORMAT] [--header HEADER]
                [--no-header] [--caseroot CASEROOT]

This utility allows the CIME user to view and modify a case's PE layout.
With this script, a user can:

1) View the PE layout of a case
   ./pelayout --format "%C:  %06T/%+H" --header "Comp: Tasks /Th"
2) Attempt to scale the number of tasks used by a case
   ./pelayout --set-ntasks 144
3) Set the number of threads used by a case
   ./pelayout --set-nthrds 2

The --set-ntasks option attempts to scale all components so that the
job will run in the provided number of tasks. For a component using the
maximum number of tasks, this will merely set that component to the new
number. However, for components running in parallel using a portion of
the maximum tasks, --set-ntasks will attempt to scale the tasks
proportionally, changing the value of ROOTPE to maintain the same level
of parallel behavior. If the --set-ntasks algorithm is unable to
automatically find a new layout, it will print an error message
indicating the component(s) it was unable to reset and no changes will
be made to the case.

Interpreted FORMAT sequences are:
%%  a literal %
%C  the component name
%T  the task count for the component
%H  the thread count for the component
%R  the PE root for the component

Standard format extensions, such as a field length and padding are supported.
Python dictionary-format strings are also supported. For instance,
--format "{C:4}", will print the component name padded to 4 spaces.

If  you encounter problems with this tool or find it is missing any
feature that you need, please open an issue on

  -h, --help            show this help message and exit
  -d, --debug           Print debug information (very verbose) to file /home/t
  -v, --verbose         Add additional context (time and file) to log messages
  -s, --silent          Print only warnings and error messages
  --set-ntasks SET_NTASKS
                        Total number of tasks to set for the case
  --set-nthrds SET_NTHRDS, --set-nthreads SET_NTHRDS
                        Number of threads to set for all components
  --format FORMAT       Format the PE layout items for each component (see
  --header HEADER       Custom header for PE layout display
  --no-header           Do not print any PE layout header
  --caseroot CASEROOT   Case directory to reference