JobTools

JobInfo(
    job_directory_prefix::AbstractString,
    mc::Type;
    checkpoint_time::Union{AbstractString, Dates.Second},
    run_time::Union{AbstractString, Dates.Second},
    tasks::Vector{TaskInfo},
    rng::Type = Random.Xoshiro,
    ranks_per_run::Union{Integer, Symbol} = 1,
)

Holds all information required for a Monte Carlo calculation. The data of the calculation (parameters, results, and checkpoints) will be saved under job_directory_prefix.

mc is the the type of the algorithm to use, implementing the abstract_mc interface.

checkpoint_time and run_time specify the interval between checkpoints and the total desired run_time of the simulation. Both may be specified as a string of format [[hours:]minutes:]seconds

Each job contains a set of tasks, corresponding to different sets of simulation parameters that should be run in parallel. The TaskMaker type can be used to conveniently generate them.

rng sets the type of random number generator that should be used.

Setting the optional parameter ranks_per_run > 1 enables Parallel run mode. The special value ranks_per_run = :all uses all available ranks for a single run.

TaskInfo(name::AbstractString, params::Dict{Symbol,Any})

Holds information of one parameter set in a Monte Carlo calculation. While it is possible to construct it by hand, for multiple tasks, it is recommended to use TaskMaker for convenience.

Special parameters

While params can hold any kind of parameter, some are special and used to configure the behavior of Carlo.

• sweeps: required. The minimum number of Monte Carlo measurement sweeps to perform for the task.

• thermalization: required. The number of thermalization sweeps to perform.

• binsize: required. The internal default binsize for observables. Carlo will merge this many samples into one bin before saving them. On top of this, a rebinning analysis is performed, so that this setting mostly affects disk space and IO efficiency. To get correct autocorrelation times, it should be 1. In all other cases much higher.

• rng: optional. Type of the random number generator to use. See rng.

• seed: optional. Optionally run calculations with a fixed seed. Useful for debugging.

• rebin_length: optional. Override the automatic rebinning length chosen by Carlo (⚠ do not set without knowing what you are doing).

• rebin_sample_skip: optional. Skip the first $N$ internal bins of each run when performing the rebinning analysis. Useful if thermalization was not set high enough at the start of the simulation.

• max_runs_per_task: optional. If set, puts a limit on the maximum number of runs that will be scheduled for this task.

Out of these parameters, it is only permitted to change sweeps for an existing calculation. This is handy to run the simulation for longer or shorter than planned originally.

result_filename(job::JobInfo)

Returns the filename of the .results.json file containing the merged results of the calculation of job.

start(job::JobInfo, ARGS)

Call this from your job script to start the Carlo command line interface.

If for any reason you do not want to use job scripts, you can directly schedule a job using

start(Carlo.MPIScheduler, job)

TaskMaker()

Tool for generating a list of tasks, i.e. parameter sets, to be simulated in a Monte Carlo simulation.

The fields of TaskMaker can be freely assigned and each time task is called, their current state will be copied into a new task. Finally the list of tasks can be generated using make_tasks

In most cases the resulting tasks will be used in the constructor of JobInfo, the basic description for jobs in Carlo.

Example

The following example creates a list of 5 tasks for different parameters T. This could be a scan of the finite-temperature phase diagram of some model. The first task will be run with more sweeps than the rest.

tm = TaskMaker()
tm.sweeps = 10000
tm.thermalization = 2000
tm.binsize = 500

task(tm; T=0.04)
tm.sweeps = 5000
for T in range(0.1, 10, length=5)
    task(tm; T=T)
end

tasks = make_tasks(tm)

task(tm::TaskMaker; kwargs...)

Creates a new task for the current set of parameters saved in tm. Optionally, kwargs can be used to specify parameters that are set for this task only.

make_tasks(tm::TaskMaker)::Vector{TaskInfo}

Generate a list of tasks from tm based on the previous calls of task. The output of this will typically be supplied to the tasks argument of JobInfo.

current_task_name(tm::TaskMaker)

Returns the name of the task that will be created by task(tm).