GENE X Bash Functions

We maintain a collection of bash functions that are specifically designed to facilitate working with GENE-X. We recommend that you include these functions in your ~/.bashrc file on any machine used for development or production.

Additionally, many of these bash functions have been integrated into ConfiX, which you can learn more about in our guide on Easy compilation with Confix.

Linking a GENE-X executable

When running the code in production, it’s often necessary to create a symbolic link to the executable from the run directory. To simplify this process, we recommend creating a custom link function:

function gxlink
{
    bname=${1:-"build"}
    bpath=${2:-$GXHOME}
    rm -f genex
    ln -s $bpath/$bname/bin/genex
}

To use the function, simply run gxlink with any options necessary in addition.

Check simulation parameters

When starting a new job, it’s not uncommon for parameter files to become corrupted or inconsistent. For instance, the number of MPI processes requested in the batch script must match the parallelization specified in the parameter file, or the simulation will stop immediately. This can be particularly frustrating if you’ve queued a long job. To prevent such issues, we recommend using the following check function to verify the consistency of your parameter file and batch script:

function gxcheck
{
    SFILE=${1:-"submit.sh"}

    echo "Parameter check..."
    ./genex -c params_in.txt

    NP_PHI=$(grep n_procs_phi params_in.txt | cut -d "=" -f 2)
    NP_MU=$(grep n_procs_mu  params_in.txt | cut -d "=" -f 2)
    NP_SP=$(grep n_procs_sp  params_in.txt | cut -d "=" -f 2)
    NP_VP=$(grep n_procs_vp  params_in.txt | cut -d "=" -f 2)
    NP_TOT=$(($NP_PHI * $NP_MU * $NP_SP * $NP_VP))

    N_NODES=$(grep "#SBATCH --nodes" $SFILE | cut -d "=" -f 2)
    N_PPN=$(grep "#SBATCH --ntasks-per-node" $SFILE | cut -d "=" -f 2)
    N_TOT=$(($N_NODES * $N_PPN))

    echo "Parallelization check..."
    if (($NP_TOT == $N_TOT))
    then
        echo " Check passed!"
    else
        echo " Check failed!"
        echo "  found" $NP_TOT "procs in params"
        echo "  found" $N_TOT "procs in submit"
    fi
}

To ensure that your parameter file and batch script are consistent, we recommend using the gxcheck function. This function performs two checks:

  1. Parameter file check: It runs the parameter check using the command ./genex -c params_in.txt, which verifies that the parameter file can be read by the code. Note that this requires that the executable genex is located in your current working directory. Further requirements are, that the (most likely login) node where you are logged in has chips with the same instruction set (e.g. AVX2) such that the code can be run in the parameter check mode.

  2. Parallelization check: It checks that the number of MPI processes specified in the params_in.txt file matches the number of processes requested in the submit script.

Simply run gxcheck (which defaults to gxcheck submit.sh) or specify a different submit script, such as gxcheck submit-intel.sh.

Clone simulation setup to another folder

When you need to run a new simulation based on a previous one, but with only minor changes to the parameters, you can use the gxcopy function to copy the relevant parameter files and submit scripts from the original simulation folder sim1 to the new folder sim2.

function cpsim
{
    sim1=$1
    sim2=${2:-"."}
    cp $sim1/params_*[!out].txt $sim1/*[!mesh].nc $sim1/*.sh $sim1/reference.out $sim2/
}
Click to enlarge

Usage is cpsim <path/to/sim1> <path/to/sim2>. By default, sim2 is ., or your current working directory.

Delete checkpoints in number range

Checkpoints are typically not required to be kept indefinitely. In most cases, it’s sufficient to retain the first, last, and a few intermediate checkpoints. To manage this, you’ll need to delete checkpoints from time to time. This command is helpful in doing so:

function rm_checkpoint
{
    for i in $(seq $1 $2) ; do rm part_"$i"/checkpoint* ; done
}

Usage is rm_checkpoint start_part end_part. For example, to delete checkpoints from ./part_2 to ./part_9, you would use the command rm_checkpoint 2 9. This will leave the checkpoints of the first and last runs intact, assuming a 10-part run.

Note

This command does not affect the moments and electromagnetic field files.

Danger

Always double-check this command before execution! To restart the code successfully, ensure that the last checkpoint is present and intact, having not been corrupted by node failure.

Useful aliases

When checking the size of a simulation, these commands are particularly useful. They produce an output that is sorted by file and folder name, with numerical values sorted within each category. This is especially helpful for simulations with a multi-part structure, where the code output is organized into multiple files and folders.

alias dul='du -lbh --max-depth=1 -- | sort -k 2 -V'