Overview of mcasopt

The mcasopt package acts as an interface between MCAS and the numerical optimisation solvers provided by scipy.optimize.minimize. It uses Slurm to run MCAS simulations on the Spartan HPC system, and wraps this in a standard Python function that can be passed to the solver.

How to use mcasopt

1. Make sure you have a copy of the file "AMDC-masses.dat"; and

2. Define a starting MCAS parameters file, which we will call "n+12C.inp";

3. Write a Python function that returns the MCAS input for a given parameter vector x, in a file that we will call n_plus_12C.py;

   Listing 2 An example mcasopt input function.

   # Define a function that returns the MCAS input for parameter vector ``x``.
   def input_fun(mcas_input, x):
       # Adjust the MCAS input according to the values in ``x``.
       mcas_input.model.v0 = [x[0], 0.0, x[1]]
       return mcas_input
   

4. Define all of the mcasopt settings and the compound states in a TOML file, which we will call "n+12C.toml" (see the example below).

   Listing 3 An example mcasopt settings file.

   [experiment]
   name = "n+12C"
   input_file = "n+12C.inp"
   mcas_path = "./mcas/mcas5.4"
   amdc_masses_path = "AMDC-masses.dat"
   input_function = "n_plus_12C.input_fun"
   x_0 = [-49, -47.1]
   runner = "local"
   
   [solver]
   method = "Nelder-Mead"
   sleep_duration = 10
   cache_file = "n+12C.cache"
   log_level = "INFO"
   epsilon = 1e-3
   
   [slurm]
   shebang = "#!/bin/bash"
   header.partition = "cascade"
   header.time = "30-00:00:00"
   header.ntasks = "1"
   header.job-name = "n+12C-job"
   header.output = "n+12C-job.log"
   modules = ["imkl"]
   
   # First resonance
   [[compound_state]]
   weight = 1.0
   energy = 0.1295
   spin = ["5/2-"]
   weight_half_width = 1.0
   half_width = 3.2125e-10
   
   # Second resonance
   [[compound_state]]
   weight = 1.0
   energy = 2.0006
   spin = ["5/2+"]
   weight_half_width = 1.0
   half_width = 1.0484e-2
   
   # Third resonance
   [[compound_state]]
   weight = 1.0
   energy = 2.6612
   spin = ["7/2+"]
   weight_half_width = 1.0
   half_width = 9.4961e-7
   

Note

See the next section, Running mcasopt on Spartan, for instructions on how to run mcasopt on Spartan.

What mcasopt does

1. Defines a function that takes a parameter vector \(x = [x_1 \ x_2 \ ... \ x_N]\) and:

   1. Use the MCAS input function \(f\) (in this case, defined in the example script) to write an MCAS input file for \(f(x)\).

   2. Launches an MCAS simulation for each of this input file, using the Slurm settings (in this case, defined in lines 17-24 of settings file);

   3. Waits until the simulation has finished; and

   4. Returns the measure \(g(x)\) of how well the MCAS simulation at location \(x\) matches the optimisation criteria defined in the settings file (lines 26-45).

2. Calls the solver, providing the function created in step #1, starting from the initial parameter vector x_0 (line 7 of the settings file), and using the solver settings (lines 10-15 of the settings file).

What the solver does

The solver will perform the following loop:

1. Evaluate the function at the current location \(x^k\). This launches an MCAS simulation (as described above), in order to evaluate the goodness of fit \(g(x^k)\).

2. When the MCAS simulation launched in step #1 has completed, the solver will either:

   • Accept \(x^k\) as the approximate solution, and return \(x^k\); or

   • Search for a new point \(x^{k+1}\) at which to evaluate the function, and return to step #1.