This section presents the usage of Promethee (1.1) environment through
[R]. In other words, how can you call any Promethee code or algorithm direclty
from your R command line.
Note: we recommend to use a good frontend for [R], like RStudio in order to make the most of R/Promethee coupling.
It is also possible to use this wrapper through the web version of Rstudio, so you can access Promethee environment from a web browser.
Here is few examples of what you can do after having loaded the wrapper and initialized the environment:
source("C:\Program Files\Promethee\promethee.R")
Promethee.init(PROMETHEE_HOME="C:\Program Files\Promethee\")
godiva = function(r) {
Promethee.run(model = "MCNP_5",input.files = file.path(PROMETHEE_HOME,"samples","godiva.p"),input.design = r)$mean_keff
}
godiva(data.frame(r=9.0))
Result:
[1] 1.02042
Again, try this function, but for many arbitrary “r” radius values: (Note that MCNP calculations are launched in parallel, thanks to Promethee environment)
godiva(data.frame(r=1:10))
Result:
[1] 0.11860 0.23928 0.36149 0.48200 0.59928 0.71293 0.82090 0.92365 1.02042
[10] 1.11112
d = Promethee.design(design="Dichotomy",input.variables=list(r="[1,20]"),fun=godiva,options=list(Output_precision=0.001,Output_target_value=1.0))
Result:
$r
[1] "8.776501196538314"
$data
[1] "| r\t| Output\t|\n| 1.0\t| 0.1186\t|\n| 20.0\t| 1.69179\t|\n| 10.5\t| 1.15292\t|\n| 8.754169698698966\t| 0.99702\t|\n| 8.743348751168663\t| 0.99634\t|\n| 8.764997608766679\t| 0.99798\t|\n| 8.787778157176508\t| 0.99989\t|\n| 8.776501196538314\t| 1.00007\t|\n| 8.799054062084672\t| 1.00265\t|\n"
$`Input parameter value`
[1] "<br/>r = 8.776501196538314<br/>Output = 1.00007<br/><img src='././dichotomy.png' width='400' height='400'/>"
$information
[1] " Output precision:\t0.001\n Output target value:\t1\n"
In details:
cat(d$data)
| r | Output |
| 1.0 | 0.1186 |
| 20.0 | 1.69179 |
| 10.5 | 1.15292 |
| 8.754169698698966 | 0.99702 |
| 8.743348751168663 | 0.99634 |
| 8.764997608766679 | 0.99798 |
| 8.787778157176508 | 0.99989 |
| 8.776501196538314 | 1.00007 |
| 8.799054062084672 | 1.00265 |
The R/Promethee wrapper does not provide a regular Sweave documentation.
Nevertheless, Roxygen doc is available within the promethee.R file:
Promethee.init(...)
#' Initialize Promethee environment.
#' example:
#' PROMETHEE_HOME="c:\\Program Files\\Promethee"
#' Promethee.init(PROMETHEE_HOME)
#' @param PROMETHEE_HOME set to Promethee installation path.
#' @param verbose.level verbosity of Promethee workbench.
#' @param headless set to TRUE to force a "no display" environment.
#' @param console.visible set to TRUE to display a Java panel with log informations. Need a graphical display environment.
#' @param math.console.visible set to TRUE to display a Java panel with math backend log informations. Need a graphical display environment.
Promethee.init <- function(PROMETHEE_HOME, verbose.level=NULL, headless=NULL, console.visible=FALSE, math.console.visible=FALSE) {}
Promethee.design(...)
#' Apply a design of experiments through Promethee environment on a response surface.
#' example of optimization using CG:
#' Promethee.design(design = "Conjugate Gradient", options = list(Maximum_iterations=10),
#' input.variables = list(a="[-2,1]",b="[-1,2]"), fun = function(X){abs(X[,1]*X[,2])})
#' @param design Design of Expetiments (DoE) given by its name (for instance ""). See .Promethee.designs global var for a list of possible values.
#' @param input.variables list of variables definition in a String (for instance x1="[-1,1]")
#' @param options list of options to pass to the DoE. All options not given are set to their default values. Note that '_' char in names will be replaced by ' '.
#' @param fun response surface as a target (say objective when optimization) function of the DoE. This should include calls to Promethee.run() function.
#' @param fun.cache set to TRUE if you wish to search in previous evaluations of fun befaore launching a new experiment. Sometimes useful when design asks for same experiments many times. Always FALSE if fun is not repeatible.
#' @param vectorize Set to "fun" (by default) if fun accepts nrows>1 data.frame input. Set to "foreach" if delegating to 'foreach' loop the parallelization of separate 'fun' calls (packages foreach required, and a DoPar needs to be registered and started before, and shutdown after). Set to "multicore" if delegating to 'multicore' the parallelization of separate 'fun' calls. Set to FALSE or "apply" means apply() will be used for serial launch of experiments.
#' @param vectorize.cores set the number of parallel execution if vectorize is set to "foreach" or "multicore". By default, set to the number of core of your computer (if known by R, otherwise set to 4).
#' @param foreach.options optional parameters to pass to the foreach DoPar. Should include anything needed for "fun" evaluation.
#' @param archive.dir define an arbitrary output directory where results (log, images) are stored.
#' @param notify.mailto destination of a mail sent (using sendmailR package, required) when design is finished. Sendmail options may be previously defined using sendmailOptions() fomr sendmailR package.
#' @return list of results from this DoE.
Promethee.design <- function(design=NULL,input.variables=NULL,options=NULL,analyse.tmp=TRUE,fun=NULL,fun.cache=FALSE,vectorize="fun",vectorize.cores=getOption("cores"),foreach.options=NULL,archive.dir=NULL,verbose.level=0,log.file=TRUE,notify.mailto=NULL,...) {}
Promethee.design.info(...)
#' Conveniency method giving information about a design available as Promethee.design() arg.
#' @return information about this design.
Promethee.design.info <- function(design=NULL, input.variables=list(x1=NULL,x2=NULL)) {}
Promethee.run(...)
#' Call an external (to R) code wrapped through Promethee environment.
#' example of usage when code is R (yes, it is a toy application :)
#' Promethee.run(model = "[R]", input.files = file.path(PROMETHEE_HOME,"samples","branin.R"),
#' input.design = list(a=runif(10), b=runif(10)), output.expressions = "z")
#' @param model name of the code wrapper to use. See .Promethee.models global var for a list of possible values.
#' @param input.files list of files to give as input for the code.
#' @param input.design data.frame of input variable values. If more than one experiment (i.e. nrow >1), experiments will be launched simultaneously on the Promethee grid.
#' @param output.expressions list of interest output from the code. Will become the names() of return list.
#' @param archive.dir define an arbitrary output directory where results (cases, csv files) are stored.
#' @param verbose.level prnt (lot of) information while running.
#' @param notify.mailto destination of a mail sent (using sendmailR package, required) when computing is finished. Sendmail options may be previously defined using sendmailOptions() fomr sendmailR package.
#' @return list of array results from the code, arrays size being equal to input.design arrays size.
Promethee.run <- function(model=NULL,input.files=NULL,input.design=NULL,output.expressions=NULL,archive.dir=NULL,force.retry=2,cache.dir=NULL,verbose.level=0,log.file=TRUE,notify.mailto=NULL) {}
Promethee.run.info(...)
#' Conveniency test & information of Promethee.run model & input.
#' @return general information concerning this model/input combination.
Promethee.run.info <- function(model=NULL,input.files=NULL) {}
Promethee.grid.info(...)
#' Conveniency overview of Promethee grid status.
#' @return String list of all visible Promethee daemons running on the network.
Promethee.grid.info <- function() {}
This section presents the usage of Promethee (1.1) environment through [R]. In other words, how can you call any Promethee code or algorithm direclty from your R command line.