This tutorial assumes you’ve generated ForceBalance inputs using my valence-fitting repository through step 04 and have the corresponding fb-fit, parameters-to-optimize, and scripts directories.

Preparing Files

Copy over

• fb-fit/

  • forcefield/force-field.offxml

  • optimize.in

  • targets.tar.gz

  • oe_license.txt (probably not needed, but I had it)

• parameters-to-optimize/ (actually these appear to be unused too)

• scripts/

The valence-fitting scripts produce the directory fb-fit/targets, so either tar them up to use the list above or wait for the whole directory to transfer.

Preparing Scripts

The scripts/hpc3_master.sh script is a template file, so you next have to modify it with your account/environment details. Specifically, I updated the #SBATCH -p line to use the free queue instead of the standard queue, and I added my UCI email to the --mail-user line. I also added the -o and -e lines to capture the output and error streams separately in files of my choosing. At least for my first attempt, I also commented out the COMPRESSED_CONDA_ENVIRONMENT stuff, leaving me with a somewhat simpler script than the one currently in the repo:

Because I wanted to run the submission scripts from the fb-fit directory instead of the scripts directory, I also edited the call to wq_worker_local.sh in scripts/submit_hpc3_worker_local.sh to point to ../scripts/wq_worker_local.sh. I also commented out the CONDA_ENVIRONMENT stuff therein and ran the script from the proper conda environment. Some of these changes will probably be reflected in the repository in the future.

Submitting

With these preparations done, you can run

Once that starts running, it will create a host file containing the HOST argument for submit_hpc3_worker_local.sh. You can obtain the PORT argument from the ForceBalance optimize.in file. Then, run the worker script with

Or for a “one-liner”

Monitoring Progress

If you use the master script from above, the primary output from ForceBalance will be directed to master.out. This is where you will see output like this:

while jobs are running, and hopefully a steady stream of output like this:

when tasks start finishing. However, if you instead see output like this:

it’s time to investigate why the tasks are failing, immediately in this case.

Debugging Failing Jobs

Using our current pipeline, the log files for workers are stored in the /tmp/$USER directory on the compute node. Unfortunately, the log for a process is deleted as soon as that process fails, making debugging tricky.

First, log in to the worker node. SSH access to the compute nodes is turned off on HPC3 by finding the jobid of the worker, and submitting an interactive job attached to that job:

srun --pty --jobid jobid --overlap /bin/bash

Navigate to /tmp/$USER and into the directory of the worker job you are interested in (by default named something like worker-2491543-177014). Note that there may be many directories and you'll have to identify which one is of interest. In the worker directory there should be a directory called t.XXXX, where XXXX is the task ID of whatever task is currently running, and inside is that task’s log file.

You can use this script to monitor the log file of a running process. It should be run in the worker directory, and the one command line input is the task ID. The script prints the content of the file as soon as it is written, so that it will be preserved when the process crashes. Because it monitors the file in real time, it may take a while to print something useful.

Once the final output is printed and the task crashes, you can use the error message to debug the issue.

One common reason for failed jobs, especially if all the jobs are failing, is the presence of constraints in the initial force field.

After the run finishes

ForceBalance output files are long. When your ForceBalance run finishes “normally” (e.g. the job didn’t crash), it will print All done at the end of the file. This doesn’t mean the optimization converged.

If your optimization converged

To find out if the optimization converged, search for Optimization Converged. If it converged, congrats! ForceBalance will print the final value of the objective function in the output file, and will save the final force field to result/optimize/force-field.offxml(unless you specified another location). Time to benchmark your run.

If your optimization didn’t converge

To find out if the optimization failed, search for Convergence Failure. ForceBalance should print the reason for the failure right before the line where it says Convergence Failure. Now it’s time to debug the failure.

Step size is too small

If ForceBalance prints something like Step size is too small to continue (4.371e-07 < 1.000e-06), it means that it has tried to take many steps in parameter space, but has determined that the optimal step is very small and thus there is likely a problem.

Try running grep "Hessian diagonal search" master.out | less. It should print something like this, for every step. Find the last few steps and examine the output.

In this part of the calcuation, ForceBalance is trying to determine what size step to take. Here, “length” refers to the proposed step length, and “result” is the resulting change in objective function. For this step, most of the proposed step sizes lead to an increase in the objective function, rather than a decrease. Additionally, there is a lot of variability in the objective function change, even when the change in step size is very small. This suggests we are on a weird part of the surface.

One way to fix this is to simply restart from a checkpoint, sometimes it converges. Another way is to restart the run with a smaller initial step size. We use finite_difference_h 0.01 as a default, try decreasing to finite_difference_h 0.001.

Geometry failed to minimize

Another possible error is that the geometry fails to minimize. This could be a one-off issue, where it fails once but gets resubmitted and succeeds that time. However, if it is consistently failing to minimize, it may be an issue with the parameters. You can visualize the parameter changes using this script to diagnose the issue.

Restarting from a checkpoint

Force balance may stop mid-way through an optimization, because the job was killed, the maximum number of steps was reached, etc. Luckily it saves a checkpoint file, called <inputfilename>.sav that records the last round of parameters and can be used to restart the job. Make sure the initial force field is the same as the initial force field from the previous run, as the parameters in the sav file are changes relative to the initial force field parameters.

Assuming your input file is called optimize.in and output files are called master.out and master.err, you can use the following script to move all the files from the previous run to a directory called round1 to keep for your records, and rename optimize.sav to optimize.in to facilitate resubmitting.