README.md

In kitbenjamin/daRtInput:

daRtInput

The goal of daRtInput is to provide a quick method of creating inputs to a Dart simulation.

This readme cannot be run through GitHub but the xml files are availble from man/data/cesbio. Users with DART installed on their system can download these and run this readme locally.

Installation

You can install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("kitbenjamin/daRtInput")

Example 1: change a property and create a sequence

#How to view groups and parameters and change the arguments of parameter

Load the package.

library(daRtInput)

Define name of your simulation and the sequence xml file (created using the ‘SequenceLauncher’ in the DART GUI). Also the path to the DART directory on your system.

#define path to DART directory
DARTprogDir <-  'C:/Users/kitbe/DART'

# name of your simulation
simName <- 'cesbio'

# sequence file name
sequenceFileXML <- 'sequence1.xml'

We can see what properties are available in the xml file and what group they are in using the getInputNames function. Unfortunately dart uses very long names.

# get group and property names
getInputNames(simName, sequenceFileXML, DARTprogDir)
#> Loading required package: xml2
#> $group1
#>      propertyNames                  type       
#> [1,] "Maket.Scene.CellDimensions.x" "enumerate"
#> 
#> $group2
#>      propertyNames                  type       
#> [1,] "Maket.Scene.CellDimensions.z" "enumerate"

Now lets define what we would like to change in the xml.

# define what properties to change and what to change them to 
propertyArgs <- list("Maket.Scene.CellDimensions.x" = c(1.5, 3, 4.5, 6))

Also we must define what DART process we want to use the sequenced files for.

# run sequence files with dart-maket
DARTprocess <- 'maket'

This function runs dart-sequencer so therefore creates simulation files for each specified propertyArg. It also creates a script file that can be exectued to run the sequence simulation.

#run dertSeqNewInputs
dartSeqNewInputs(simName, sequenceFileXML, propertyArgs, DARTprogDir, DARTprocess)

The sequence1.xml has been edited such that the property ‘Maket.Scene.CellDimensions.x’ now has the specified property arguments, ’1.5;3;4.5;6". You will also see the directory daRtInput//simName has been created and within this directory is sequence files, one for each combination of propertyArgs. Within each sequence file is a script file (shell or batch depending on operting system), which is capable of running the sequence file through dart-maket. Furthermore a database is created, containing a job tracking table (JTT) that can be used to track the status of the sequenced simulations if running them on a remote server.

In summary, dartSeqNewInputs essentially carries out two processes: 1. editing the xml file that defines the arguments input into DART. 2. creates sequenced simulation files for each combination of arguments, creates a script file that can execute the simulation folder for the given DART process and creates a job tracking table.

These two processes can be carried out seperately. The fist function:

#edit sequence xml file. Note that as newSequenceFileXML is not defined, sequenceFileXML will be overwritten
editSequence(simName, sequenceFileXML, propertyArgs, DARTprogDir)

The second function:

# make sequenced simulation folders and the scripts to execute them
makeSequenceJobScripts(simName, sequenceFileXML,  DARTprogDir, DARTprocess)

EXAMPLE 2: change multiple properties

This time we are changing arguments for multiple propertys. we will also choose to run dart-phase.

# define the input arguments as a list of vectors
propertyArgs <- list("Maket.Scene.CellDimensions.x" = c(1, 2, 3, 4, 5, 6), "Maket.Scene.CellDimensions.z" = c(2, 4, 6))

#run dart-phase
DARTprocess <- 'phase'

This time, instead of overwritting the sequence XML file we shall create a new file called sequence1_ex2.xml

# give the sequence xml a new name
newSequenceFileXML <- 'sequence1_ex2.xml'

Also we shall define a description name for the directory containing the sequence files (as opposed to the datetime).

# define user description
userDesc <- 'example2'

This time sequenced folders will be within a directory named userDesc instead of datetime.

#run dertSeqNewInputs
dartSeqNewInputs(simName, sequenceFileXML, propertyArgs, DARTprogDir, DARTprocess,
                 newSequenceFileXML = newSequenceFileXML, userDesc = userDesc)

This time, a new xml file named ‘sequence1_ex2.xml’ has been generated. In addition, there are 18 sequence files within a directory named example2. There are 18 because this is the product of the lengths of the new arguments. A sequence for every combination of x and z is created. In this case, a sequence is created for x = 1 z = 2, x = 1 z = 4, x = 1 z = 6, x = 2 z = 2 and so on.

EXAMPLE 3: changing properties in the same group

This time using sequence 2

# sequence file name
sequenceFileXML <- 'sequence2.xml'

# view the new inputs
getInputNames(simName, sequenceFileXML, DARTprogDir)
#> $group1
#>      propertyNames                  type       
#> [1,] "Maket.Scene.CellDimensions.x" "enumerate"
#> [2,] "Maket.Scene.CellDimensions.z" "enumerate"
#> 
#> $group2
#>      propertyNames                                   type       
#> [1,] "Coeff_diff.Temperatures.ThermalFunction.meanT" "enumerate"

Notice two properties in group1- horizontal and vertical cell dimensions and one property in group2- mean temperature. Properties in the the same group are sequenced simulataniously so must have the same length.

# define the input arguments as a list of vectors
propertyArgs <- list("Maket.Scene.CellDimensions.x" = c(1, 2, 3, 4), 
                     "Maket.Scene.CellDimensions.z" = c(1, 2, 3, 4), 
                     "Coeff_diff.Temperatures.ThermalFunction.meanT" = c(273, 278, 283, 288, 293, 298))

It’s also possible to run multiple processes.

#run dart-directons and dart-maket
DARTprocess <- DARTprocess <- c('directions', 'maket')

To create the sequence files, dart-sequence is run. To avoid the possiblilty of infinite loops, a timeout is set for dart-sequence. This ‘maxTime’ is set by default to 120 seconds however if you are creating large number of sequences then you may wish to increase this time my settin maxTime to 180 for example.

#run dertSeqNewInputs
dartSeqNewInputs(simName, sequenceFileXML, groupNames, propertyNames, propertyArgs, DARTprogDir, DARTprocess, maxTime = 180)

This time 24 sequences have been created- this is the product of the length of arguments in group 1 (4) and the length of the argument in group 2 (6). In this case a sequence is created for x = 1 z = 1 temperature = 273, x = 2 z = 2 temperature = 273, x = 3 z = 3 temperature = 273, x = 4 z = 4 temperature = 273, x = 1 z = 1 temperature = 278 and so on.

kitbenjamin/daRtInput documentation built on July 10, 2021, 1 p.m.