Home News Downloads Documentation
Home Downloads Introduction Getting Started Examples
Contact Publications

Simulation options

Sample simulation options can be found in:

  • simulation_options-ode.json (for ODE systems)
  • simulation_options-dae.json (for DAE systems)

Section Simulation

Option Suboption Description
StartTime Simulation initial time (currently ignored)
TimeHorizon Simulation final time.
ReportingInterval The time interval for obtaining simulation results
OutputDirectory Name or a full path to the directory where the results, stats and log messages are saved. The default is: results-[%d.%m.%Y-%H.%M.%S].
Log
Name One of:
  • "StdOut": messages are sent to std output
  • "TextFile": messages are saved into a text file
Parameters "StdOut": no parameters
"TextFile":
  • "fileName" (name of the log file)
DataReporter
Name One of:
  • "CSV": the results are saved in .csv format
  • "HDF5": the results are saved in .hdf5 format
Parameters Common parameters for "CSV" and "HDF5" data reporters:
  • "fileNameResults": filename where the variables will be saved
    (if empty the results are not reported)
  • "fileNameDerivatives": filename where the derivatives will be saved
    (if empty the derivatives are not reported)
If "fileNameResults" is set to "results.csv" the simulation results will be stored in "results-0.csv", "results-1.csv", ..., "results-Npe.csv" files (one file per every processing element).
"CSV" specific parameters:
  • "outputFormat": "fixed" or "scientific" notation
  • "delimiter": default ";" (comma ',' should be avoided since it can appear in variable names)
  • "precision": the number of decimal digits

Sample Log and HDF5 DataReporter specification: 
    "Log": {
        "Name": "StdOut",
        "Parameters": {
        }
    },
    "DataReporter": {
        "Name": "HDF5",
        "Parameters": {
            "fileNameResults":     "results.hdf5",
            "fileNameDerivatives": "derivatives.hdf5"
        }
    }
Sample Log and CSV DataReporter specification: 
    "Log": {
        "Name": "TextFile",
        "Parameters": {
            "fileName": "results.log"
        }
    },
    "DataReporter": {
        "Name": "CSV",
        "Parameters": {
            "fileNameResults":     "results.csv",
            "fileNameDerivatives": "derivatives.csv",
            "outputFormat":        "fixed",
            "delimiter":           ";",
            "precision":           15
        }
    }

Section Model

Contains specification about equation evaluators. 
"Model": {
        "Evaluators": {
            "Device_0": {},
            "Device_1": {},
            ...
            "Device_N": {}
        }
    }
where each Device_x contains: 
    "Device_0": {
        "Library": "",
        "Name": "",
        "Parameters": {},
        "Groups": [], 
        "Kernels": []
    }
Group evaluators can evaluate only group of equations while kernel evaluators only kernels.
Option Suboption Description
Device_xx
Library Group evaluators, one of:
  • "Sequential": equations evaluated sequentially
  • "OpenMP": use OpenMP API for evaluation of equations
  • "OpenCL": use OpenCL framework for evaluation of equations
  • "OpenCL_FPGA": use OpenCL framework and FPGA device for evaluation of equations (at the moment only FPGA emulator)
Kernel evaluators, one of:
  • "Kernels_Sequential": kernels evaluated sequentially
  • "Kernels_OpenMP": use OpenMP API for evaluation of kernels
  • "Kernels_OpenCL": use OpenCL framework for evaluation of kernels
  • "VectorisedKernels_OpenMP": use OpenMP API for evaluation of auto- or explicitly vectorised kernels
  • "Kernels_OpenCL_FPGA": use OpenCL framework and FPGA device for evaluation of equations (at the moment only FPGA emulator)
  • "Kernels_Kokkos": use Kokkos programming model for evaluation of kernels
  • "Kernels_SYCL": use SYCL programming model for evaluation of kernels
Name Any suitable name to distinguish between multiple evaluators.
Parameters "Sequential": no parameters
"OpenMP":
  • "numThreads": the number of threads (if 0 the default number is used, typically the number of cores). The default is 0.
"Kernels_OpenMP" and VectorisedKernels_OpenMP:
  • "numThreads": the number of threads (if 0 the default number is used, typically the number of cores). The default is 0.
"Kernels_Sequential": None
"OpenCL":
  • "platformID": identifier returned by clGetPlatformIDs function
  • "deviceID": identifier returned by clGetDeviceIDs function
  • "buildProgramOptions": string with compiler options to pass to clBuildProgram function. The default is empty string.
"OpenCL_FPGA": None
  • "platformID": identifier returned by clGetPlatformIDs function
  • "deviceID": identifier returned by clGetDeviceIDs function
  • "vendor": string (Intel or AMD). The default is empty string.
  • "board": string, representing the target board name. The default is 'emulator' string (uses FPGA emulator to emulate the device).
"Kernels_OpenCL":
  • "platformID": identifier returned by clGetPlatformIDs function
  • "deviceID": identifier returned by clGetDeviceIDs function
  • "buildProgramOptions": string with compiler options to pass to clBuildProgram function. The default is empty string.
  • "API": string, one of "C++" or "C99" used to load generated kernels from "OpenCL" or "OpenCL_C99" sub-directories of the "KernelName" directory, respectively. The default is "C++" (contains C++ OpenCL kernels).
"VectorisedKernels_OpenMP":
  • "numThreads": the number of threads (if 0 the default number is used, typically the number of cores). The default is 0.
"Kernels_OpenCL_FPGA": None
  • "platformID": identifier returned by clGetPlatformIDs function
  • "deviceID": identifier returned by clGetDeviceIDs function
  • "vendor": string ("Intel" or "AMD").
  • "board": string, representing the target board name. The default is 'emulator' string (uses FPGA emulator to emulate the device).
"Kernels_Kokkos": None "Kernels_SYCL": None
Groups A list of groups to be evaluated by a particular evaluator.
Kernels A list of kernels to be evaluated by a particular evaluator.

Sample Sequential evaluator specification: 
    "Device_x" : {
        "Library" : "Sequential",
        "Name": "seq",
        "Parameters": {},
        "Groups": ["GroupName1", "GroupName2"]
    }
Sample OpenMP evaluator specification: 
    "Device_x" : {
        "Library" : "OpenMP",
        "Name": "omp",
        "Parameters": {
            "numThreads" : 0
        },
        "Groups": ["GroupName1", "GroupName2"]
    }
Sample OpenCL evaluator specification: 
    "Device_x" : {
        "Library" : "OpenCL",
        "Name": "ocl",
        "Parameters": {
            "platformID" :          0,
            "deviceID" :            0,
            "buildProgramOptions" : ""
        },
        "Groups": ["GroupName1", "GroupName2"]
    }
Sample Kernels_Sequential evaluator specification: 
    "Device_x" : {
        "Library" : "Kernels_Sequential",
        "Name": "seq",
        "Parameters": {},
        "Kernels": ["KernelName1", "KernelName2"]
    }
Sample Kernels_OpenMP evaluator specification: 
    "Device_x" : {
        "Library" : "Kernels_OpenMP",
        "Name": "omp",
        "Parameters": {
            "numThreads" : 0
        },
        "Kernels": ["KernelName1", "KernelName2"]
    }
Sample Kernels_OpenCL evaluator specification: 
    "Device_x" : {
        "Library" : "Kernels_OpenCL",
        "Name": "ocl",
        "Parameters": {
            "platformID" :          0,
            "deviceID" :            0,
            "buildProgramOptions" : "",
            "API":                  "C99"
        },
        "Kernels": ["KernelName1", "KernelName2"]
    }
Sample OpenCL_FPGA evaluator specification: 
    "Device_x" : {
        "Library": "OpenCL_FPGA",
        "Name": "ocl_fpga",
        "Parameters": {
            "platformID": 0,
            "deviceID": 0,
            "vendor": "",
            "board": "emulator"
        },
        "Groups": ["DefaultGroup"],
    }
Sample Kernels_OpenCL_FPGA evaluator specification: 
    "Device_x" : {
        "Library": "Kernels_OpenCL_FPGA",
        "Name": "kocl_fpga",
        "Parameters": {
            "platformID": 0,
            "deviceID": 0,
            "vendor": "Intel",
            "board": "emulator"
        },
        "Groups": ["DefaultGroup"],
    }

Section Solver

Option Description
Library "Sundials"
Name One of:
  • "IDAS": use SUNDIALS IDAS DAE solver
  • "CVodes": use SUNDIALS CVodes ODE solver
PrintInfo Print additional debug information to stdout.
Parameters "Common parameters":
  • "RelativeTolerance": default 1e-5 (float)
  • "IntegrationMode": "Normal" or "OneStep"
"IDAS" specific:
  • "MaxOrd": default 5 (integer)
  • "MaxNumSteps": default 500 (integer)
  • "InitStep": default 0.0 (float)
  • "MaxStep": default 0.0 (float)
  • "MaxErrTestFails": default 10 (integer)
  • "MaxNonlinIters": default 4 (integer)
  • "MaxConvFails": default 10 (integer)
  • "NonlinConvCoef": default 0.33 (float)
  • "NoInactiveRootWarn": default false (bool)
  • "SuppressAlg": default false (bool)
  • "NonlinConvCoefIC": default 0.0033 (float)
  • "MaxNumStepsIC": default 5 (integer)
  • "MaxNumJacsIC": default 4 (integer)
  • "MaxNumItersIC": default 10 (integer)
  • "LineSearchOffIC": default false (bool)
"CVodes" specific:
  • "LinearMultistepMethod": "BDF" or "Adams"
  • "IterationType": "Newton" or "Functional"
  • "MaxOrd": default 5 (integer)
  • "MaxNumSteps": default 500 (integer)
  • "InitStep": default 0.0 (float)
  • "MinStep": default 0.0 (float)
  • "MaxStep": default 0.0 (float)
  • "MaxHnilWarns": default 1.0 (float)
  • "StabLimDet": default false (bool)
  • "MaxErrTestFails": default 7 (integer)
  • "MaxNonlinIters": default 3 (integer)
  • "MaxConvFails": default 10 (integer)
  • "NonlinConvCoef": default 0.10 (float)
  • "NoInactiveRootWarn": default false (bool)

More info about solver parameters can be found in IDAS and CVodes user guides.

Section LinearSolver

Option Description
Library One of:
  • "Sundials"
  • "Trilinos"
Name "Sundials" solvers (SPILS):
  • "gmres": generalised minimal residual iterative solver
"Trilinos" solvers:
  • "Amesos_Klu": Trilinos Amesos KLU
  • "AztecOO": AztecOO iterative solvers (the actual solver specified using "AZ_solver" parameter)
PrintInfo Print additional debug information to stdout.
Parameters Generic:
  • "SaveMatrixImage": default false (boolean)
SUNDIALS "gmres" specific:
  • "kspace": default 30 (integer)
  • "preconditioningType": "left", "right", "both" or "none"
  • "EpsLin": default 0.05 (float)
  • "JacTimesVecFn": "DifferenceQuotient", "JacobianVectorMultiply" or "DifferenceQuotient_timed"
  • "GSType": "MODIFIED_GS" or "CLASSICAL_GS"
"Amesos" specific:
  • "AddZeroToDiag": if true, insert a zero element on the diagonal of the matrix, default false (bool)
  • "PrintTiming": print timing information when the AMESOS object is destroyed, default false (bool)
  • "PrintStatus": print information about the linear system and the solver when the AMESOS object is destroyed, default false (bool)
  • "OutputLevel": the level of output printed on the standard output, default 0 (integer)
  • "Refactorize": controls the use of a prior symbolic and numeric factorization, default false (bool)
  • "ScaleMethod": scaling of the input matrix prior to factorization, default 0 (integer)
"AztecOO" specific:
  • "AZ_solver": "AZ_cg" (conjugate gradient), "AZ_cg_condnum" (conjugate gradient with condition number estimation), "AZ_gmres" (restarted generalized minimal residual), "AZ_gmres_condnum" (restarted GMRES with condition number estimation), "AZ_cgs" (conjugate gradient squared), "AZ_tfqmr" (transpose-free quasi-minimal residual) or "AZ_bicgstab" (bi-conjugate gradient with stabilization)
  • "AZ_kspace": Krylov subspace size for restarted GMRES, default 30 (integer)
  • "AZ_tol": tolerance for convergence tests, default 1e-6 (float)
  • "AZ_scaling": "AZ_none", "AZ_Jacobi", "AZ_BJacobi", "AZ_row_sum", "AZ_sym_diag", "AZ_sym_row_sum", "AZ_equil" or "AZ_sym_BJacobi"
  • "AZ_reorder": if 1 perform RCM reordering for incomplete factorisations, default 1 (integer)
  • "AZ_conv": "AZ_r0", "AZ_rhs", "AZ_Anorm", "AZ_noscaled", "AZ_sol" or "AZ_weighted"
  • "AZ_keep_info": keep matrix factorization information after solve, default 0 (integer)
  • "AZ_max_iter": maximum number of iterations, default 500 (integer)
  • "AZ_orthog": "AZ_classic" or "AZ_modified"
  • "AZ_pre_calc": "AZ_calc", "AZ_recalc" or "AZ_reuse"
  • "AZ_output": "AZ_all", "AZ_none", "AZ_last", "AZ_summary" or "AZ_warnings"

More info about solver parameters can be found in IDAS, CVodes, Amesos and AztecOO user guides.
Preconditioner See below

Sub-section Preconditioner:
Option Description
Library One of:
  • "AztecOO" (native AztecOO preconditioners)
  • "Ifpack"
  • "ML"
Name "AztecOO": ignored (name specified using "AZ_precond" and "AZ_subdomain_solve" options)
"Ifpack" supported preconditioners:
  • "Amesos": complete LU factorisation
  • "ILU": incomplete LU factorisation
  • "ILUT": incomplete LU factorisation with threshold
  • "Amesos": complete LU factorisation
  • "IC": incomplete Cholesky factorisation
  • "ICT": incomplete Cholesky factorisation with threshold
"ML" supported preconditioners:
  • "SA": classical smoothed aggregation
  • "DD": domain decomposition
  • "DD-ML": domain decomposition
  • "NSSA": nonsymmetric smoothed aggregation
PrintInfo Print additional debug information to stdout.
Parameters Generic:
  • "SaveMatrixImage": default false (boolean)
"AztecOO" preconditioner parameters:
  • "AZ_precond": "AZ_none", "AZ_Jacobi", "AZ_Neumann", "AZ_ls", "AZ_sym_GS" or "AZ_dom_decomp"
  • "AZ_subdomain_solve": "AZ_lu", "AZ_ilu", "AZ_ilut", "AZ_rilu", "AZ_bilu" or "AZ_icc"
  • "AZ_graph_fill": fill-in (k) for incomplete factorisations ILU, ICC and BILU, default 0 (integer)
  • "AZ_ilut_fill": fill-in for ILUT factorisation, default 1.0 (float)
  • "AZ_drop": LU and ILUT drop tolerance, default 0.0 (float)
  • "AZ_athresh": absolute magnitude of the diagonal entries of the matrix (α), default 0.0 (float)
  • "AZ_rthresh": relative magnitude of the diagonal entries of the matrix (ρ), default 0.0 (float)
  • "AZ_omega": relaxation parameter for RILU (ω): if 0 it transfoms into ILU, and if 1 it transforms into MILU, default 1.0 (float)
"Ifpack" preconditioner parameters:
  • "fact: level-of-fill": fill-in (k) for incomplete ILU and ICC factorisations, default 0 (integer)
  • "fact: ilut level-of-fill": fill-in for ILUT factorisation, default 0.0 (float)
  • "fact: drop tolerance": ILUT drop tolerance, default 1e-12 (float)
  • "fact: relax value": relaxation parameter for RILU (ω): if 0 it transfoms into ILU, and if 1 it transforms into MILU, default 0.0 (float)
  • "fact: absolute threshold": absolute magnitude of the diagonal entries of the matrix (α), default 0.0 (float)
  • "fact: relative threshold": relative magnitude of the diagonal entries of the matrix (ρ), default 1.0 (float)
  • "amesos: solver type": "Amesos_Klu"
For incomplete factorisations, a-priori diagonal perturbation is defined as: d[i] = sign(d[i]) · α + d[i] · ρ, where α and ρ are absolute and relative thresholds, respectively.

More info about parameters can be found in AztecOO, Ifpack and ML user guides.

Sample Sundials gmres linear solver with Ifpack ILU preconditioner specification: 
    "LinearSolver": {
        "Library":   "Sundials",
        "Name":      "gmres",
        "PrintInfo": false,
        "Parameters": {
            "kspace":            30,
            "EpsLin":            0.05,
            "JacTimesVecFn":     "DifferenceQuotient",
            "DQIncrementFactor": 1.0,
            "MaxRestarts":       5,
            "GSType":            "MODIFIED_GS"
        },
        "Preconditioner" : {
                "Library" :  "Ifpack",
                "Name":      "ILU",
                "PrintInfo": false,
                "Parameters": {
                    "SaveMatrixImage":          false,
                    "fact: level-of-fill":      3,
                    "fact: relax value":        0.0,
                    "fact: absolute threshold": 1e-5,
                    "fact: relative threshold": 1.0
                }
            }
    }
Sample Sundials gmres linear solver with Ifpack ILUT preconditioner specification: 
    "LinearSolver": {
        "Library":   "Sundials",
        "Name":      "gmres",
        "PrintInfo": false,
        "Parameters": {
            "kspace":            30,
            "EpsLin":            0.05,
            "JacTimesVecFn":     "DifferenceQuotient",
            "DQIncrementFactor": 1.0,
            "MaxRestarts":       5,
            "GSType":            "MODIFIED_GS"
        },
        "Preconditioner" : {
        "Library":   "Ifpack",
        "Name":      "ILUT",
        "PrintInfo": false,
        "Parameters": {
            "fact: ilut level-of-fill": 3.0,
            "fact: drop tolerance":     1e-10,
            "fact: relax value":        0.0,
            "fact: absolute threshold": 1e-5,
            "fact: relative threshold": 1.0
        }
    }
Sample Trilinos Amesos linear solver specification: 
    "LinearSolver": {
        "Library":   "Trilinos",
        "Name":      "Amesos_Klu",
        "PrintInfo": false,
        "Parameters": {
            "SaveMatrixImage": false
        }
    }
Sample Trilinos AztecOO gmres linear solver with native AztecOO ILU preconditioner specification: 
    "LinearSolver": {
        "Library":   "Trilinos",
        "Name":      "AztecOO",
        "PrintInfo": false,
        "Parameters": {
            "AZ_solver":     "AZ_gmres",
            "AZ_kspace":     30,
            "AZ_scaling":    "AZ_none",
            "AZ_reorder":    1,
            "AZ_conv":       "AZ_r0",
            "AZ_keep_info":  1,
            "AZ_max_iter":   500,
            "AZ_orthog":     "AZ_modified",
            "AZ_pre_calc":   "AZ_calc",
            "AZ_output":     "AZ_warnings"
        },
        "Preconditioner": {
            "Library":   "AztecOO",
            "Name":      "",
            "PrintInfo": false,
            "Parameters": {
                "AZ_precond":          "AZ_dom_decomp",
                "AZ_subdomain_solve":  "AZ_ilu",
                "AZ_graph_fill":       3,
                "AZ_athresh":          1e-05,
                "AZ_rthresh":          1.0,
                "SaveMatrixImage":     false
            }
        }
    }
Sample Trilinos AztecOO gmres linear solver with Ifpack ILU preconditioner specification: 
    "LinearSolver": {
        "Library":  "Trilinos",
        "Name":     "AztecOO",
        "PrintInfo": false,
        "Parameters": {
            "AZ_solver":     "AZ_gmres",
            "AZ_kspace":     30,
            "AZ_scaling":    "AZ_none",
            "AZ_reorder":    1,
            "AZ_conv":       "AZ_r0",
            "AZ_keep_info":  1,
            "AZ_max_iter":   500,
            "AZ_orthog":     "AZ_modified",
            "AZ_pre_calc":   "AZ_calc",
            "AZ_output":     "AZ_none"
        },
        "Preconditioner" : {
            "Library":   "Ifpack",
            "Name":      "ILU",
            "PrintInfo": false,
            "Parameters": {
                "fact: level-of-fill":      3,
                "fact: relax value":        0.0,
                "fact: absolute threshold": 1e-5,
                "fact: relative threshold": 1.0
            }
        }
    }
Sample Trilinos AztecOO gmres linear solver with Ifpack Amesos preconditioner specification: 
    "LinearSolver": {
        "Library":  "Trilinos",
        "Name":     "AztecOO",
        "PrintInfo": false,
        "Parameters": {
            "AZ_solver":     "AZ_gmres",
            "AZ_kspace":     30,
            "AZ_scaling":    "AZ_none",
            "AZ_reorder":    1,
            "AZ_conv":       "AZ_r0",
            "AZ_keep_info":  1,
            "AZ_max_iter":   500,
            "AZ_orthog":     "AZ_modified",
            "AZ_pre_calc":   "AZ_calc",
            "AZ_output":     "AZ_all"
        },
        "Preconditioner" : {
            "Library":   "Ifpack",
            "Name":      "Amesos",
            "PrintInfo": false,
            "Parameters": {
                "amesos: solver type": "Amesos_Klu"
            }
        }
    }

Copyright: Dragan D. Nikolić, DAE Tools Project 2009-2023