Simplace’s documentation!¶

The package offers two interfaces to the simulation framework Simplace.

Procedural interface with functions and procedures
Object oriented interface with objects and methods

Procedural interface¶

Control the simulation framework Simplace.

You need Java >= 11.0 and the Simplace simulation framework http://www.simplace.net/

Example 1 - Running a project:

>>> import simplace
>>> sp = simplace.initSimplace('/ws/','/runs/simulation/','/out/')
>>> simplace.setProjectLines(sp, [1,3,8,9,17])
>>> simplace.openProject(sp, '/sol/Maize.sol.xml', '/proj/NRW.proj.xml')
>>> simplace.runProject(sp)
>>> simplace.closeProject(sp)

Example 2 - Running a solution with changed simulation parameters:

>>> import simplace
>>> sp = simplace.initSimplace('/ws/','/runs/simulation/','/out/')
>>> simplace.openProject(sp, '/sol/Maize.sol.xml')
>>> simid = simplace.createSimulation(sp, {'vLUE':3.2,'vSLA':0.023})
>>> simplace.runSimulations(sp)
>>> result = simplace.resultToList(simplace.getResult(sp,'YearOut',simid))
>>> simplace.closeProject(sp)
>>> print(result['BiomassModule.Yield'])
805.45

simplace.closeProject(simplaceInstance)[source]¶

Close the project.

Parameters:: simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace

simplace.createSimulation(simplaceInstance, parameters=None, queue=True)[source]¶

Create a single simulation and set initial parameters.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
parameters (dict) – key-value pairs where the key has to match the Simplace SimVariable name (optional)
queue (bool) – if true add the simulation to the queue of simulations, else empty the queue before adding the simulation

Returns:

id of the created simulation

Return type:

str

simplace.findFirstSimplaceInstallation(directories=[], tryStandardDirs=True, simulationsDir='simplace_run', ignoreSimulationsDir=False)[source]¶

Returns the path of the first simplace installation found

Parameters:

directories (list) – List of paths where to check for simplace subfolders
tryStandardDirs (bool) – Check additionally for common standard locations
simulationsDir (str) – directory that contains user simulations
ignoreSimulationsDir (bool) – don’t check for the simulations directory

Returns:

Path to first Simplace installation found

Return type:

str

simplace.findSimplaceInstallations(directories=[], tryStandardDirs=True, firstMatchOnly=False, simulationsDir='simplace_run', ignoreSimulationsDir=False, verbose=True)[source]¶

Returns a list of simplace installations

Parameters:

directories (list) – list of paths where to check for simplace subfolders
tryStandardDirs (bool) – check additionally for common standard locations
firstMatchOnly (bool) – return only the first matching directory
simulationsDir (str) – directory that contains user simulations
ignoreSimulationsDir (bool) – don’t check for the simulations directory
verbose (bool) – print addtional messages

Returns:

List of paths to Simplace installations

Return type:

list

simplace.getDatatypesOfResult(result)[source]¶

Get the list of datatypes of the output variables.

Parameters:: result – handle to simulation result (as returned by getResult())
Returns:: dictionary where the variable names are keys and the datatypes are the values
Return type:: dict

simplace.getResult(simplaceInstance, output, simulation=None)[source]¶

Get a specific output of a finished simulation.

If the parameter simulation is not given, the results of all simulation will be returned.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
output (str) – id of the memory output
simulation (str) – simulation id (optional)

Returns:

handle to simulation output. To access the variables, convert the items by resultToList

Return type:

Result

simplace.getSimplaceDirectories(simplaceInstance)[source]¶

Get work-, output-, projects- and data-directory.

Parameters:: simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
Returns:: dictionary with the actual paths for work-, outputdir etc.
Return type:: dict

simplace.getSimulationIDs(simplaceInstance)[source]¶

Get the ids of ready to run simulations.

Parameters:: simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
Returns:: list of simulation ids
Return type:: list

simplace.getUnitsOfResult(result)[source]¶

Get the list of units of the output variables.

Parameters:: result – handle to simulation result (as returned by getResult())
Returns:: dictionary where the variable names are keys and the units are the values
Return type:: dict

simplace.initSimplace(installDir=None, workDir=None, outputDir=None, projectsDir=None, dataDir=None, additionalClasspathList=[], javaParameters=None)[source]¶

Initialisation of Simplace

Start the java virtual machine and initialize the Simplace framework. You have to call this function first.

Parameters:

installDir (str) – Where your simplace_core, simplace_modules, simplace_run etc. reside
workDir (str) – Working directory for Simplace solutions, projects
outputDir (str) – Output files will be written there
projectsDir (str) – Optional folder for project data
dataDir (str) – Optional folder for input data
additionalClasspathList (list) – List with addtional classpaths
javaParameters (str[]) – Parameter list passed to the java virtual machine

Returns:

A reference to an instance of SimplaceWrapper: java class

Return type:

SimplaceWrapper

simplace.initSimplaceDefault(setting='run')[source]¶

Initialises Simplace with work- and outputdir for different settings

Parameters:

setting (str) – one of ‘run’, ‘modules’, ‘lapclient’ or ‘wininstall’

Returns:

A reference to an instance of SimplaceWrapper: java class

Return type:

SimplaceWrapper

simplace.openProject(simplaceInstance, solution, project=None, parameters=None)[source]¶

Initialises a project from the solution and optional project file.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
solution (str) – path (absolute or relative to workDir) to solution file
project (str) – path (abs. or rel. to workDir) to project file (optional)
parameters (dict) – key-value pairs where the key has to match the Simplace SimVariable name (optional)

simplace.resultToList(result, expand=True, start=None, end=None, legacy=False)[source]¶

Convert the output to a python dictionary

Parameters:

result – handle to simulation result (as returned by getResult())
expand (bool) – whether array values should be expanded to lists or kept as handles to java objects (optional)
start (int) – number of first entry to fetch (optional)
end (int) – number of last entry to fetch (optional)
legacy (bool) – if True, don’t use numpy (optional)

Returns:

simulation results as key-value pairs. Keys are the simulation variable nams, values are lists of simulated daily/yearly values

Return type:

dict

simplace.runProject(simplaceInstance)[source]¶

Run the project.

Parameters:: simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace

simplace.runSimulations(simplaceInstance, selectsimulation=False)[source]¶

Run created simulations.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
selectsimulation (bool) – if true, it keeps a selected simulation (not yet usable)

simplace.setAllSimulationValues(simplaceInstance, parameterlist)[source]¶

Set values of all simulations in queue.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
parameterlist (list) – a list of dictinaries with key-value pairs where the key has to match the Simplace SimVariable name

simplace.setCheckLevel(simplaceInstance, level)[source]¶

Set the checklevel of the solution. OFF does no checks, STRICT does most severe checks.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
level (str) – possible values: “CUSTOM,”STRICT”,”INTENSE”,”LAZY”,”OFF”, “ONLY”

simplace.setLogLevel(level)[source]¶

Set the log’s verbosity. FATAL is least verbose, TRACE most verbose

Parameters:: level (str) – possible values from least verbose ‘FATAL’ via ‘ERROR’, ‘WARN’, ‘INFO’, ‘DEBUG’ to most verbose ‘TRACE’

simplace.setProjectLines(simplaceInstance, lines)[source]¶

Set the line numbers of the project data file used for simulations.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
lines (str) – a string with line specifications, e.g. “3-10,15,30-33” or a list of linenumbers [1,2,9,11]

simplace.setSimplaceDirectories(simplaceInstance, workDir=None, outputDir=None, projectsDir=None, dataDir=None)[source]¶

Set work-, output-, projects- and data-directory.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
workDir (str) – path to working directory
outputDir (str) – path to output directory
projectsDir (str) – path to projects directory
dataDir (str) – path to data directory

simplace.setSimulationValues(simplaceInstance, parameters)[source]¶

Set values of actual simulation that runs stepwise.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
parameters (dict) – key-value pairs where the key has to match the Simplace SimVariable name

simplace.setSlotCount(count)[source]¶

Set the maximum numbers of processor cores used when running projects.

Parameters:: count (int) – maximal numbers of processor cores used.

simplace.shutDown(simplaceInstance)[source]¶

Stops the java virtual machine.

Parameters:: simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace

simplace.stepAllSimulations(simplaceInstance, count=1, parameterlist=None, varFilter=None)[source]¶

Run all simulations in queue stepwise.

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
count (int) – number of steps to perform
parameterlist (list) – a list of dictinaries with key-value pairs where the key has to match the Simplace SimVariable name
varFilter (list) – list of variable names to be included in the result. If not set, all variables are returned

Returns:

list of handles to simulation variables (possibly filtered). To access the variables, convert the items by varmapToList

Return type:

list

simplace.stepSimulation(simplaceInstance, count=1, parameters=None, varFilter=None, simulationnumber=0)[source]¶

Run specific simulation stepwise (default first simulation in queue).

Parameters:

simplaceInstance – handle to the SimplaceWrapper object returned by initSimplace
count (int) – number of steps to perform
parameters (dict) – key-value pairs where the key has to match the Simplace SimVariable name
varFilter (list) – list of variable names to be included in the result. If not set, all variables are returned
simulationnumber (int) – number of simulation in the queue that should be run stepwise (default first simulation)

Returns:

handle to simulation variables (possibly filtered). To access the variables, convert the result by varmapToList

Return type:

VarMap

simplace.varmapToList(varmap, expand=True, legacy=False)[source]¶

Convert the values of the last simulation step to a python dictionary.

Parameters:

varmap – handle to simulation varmap (as returned by stepSimulation())
expand (bool) – whether array values should be expanded to lists or kept as handles to java objects (optional)
legacy (bool) – if True, don’t use numpy (optional)

Returns:

simulation values as key-value pairs. Keys are the simulation variable nams, values are the values from last simulation step

Return type:

dict

Object oriented interface¶

Control the simulation framework Simplace - Object oriented interface.

It wraps the functions from the simplace package to a class.

You need Java >= 11.0 and the Simplace simulation framework http://www.simplace.net

Example 1 - Running a project:

>>> import simplace
>>> sim = simplace.SimplaceInstance('/ws/','/runs/simulation/','/out/')
>>> sim.setProjectLines([1,3,8,9,17])
>>> sim.openProject('/sol/Maize.sol.xml', '/proj/NRW.proj.xml')
>>> sim.runProject()
>>> sim.closeProject()

Example 2 - Running a solution with changed simulation parameters:

>>> import simplace
>>> sim = simplace.SimplaceInstance('/ws/','/runs/simulation/','/out/')
>>> sim.openProject('/sol/Maize.sol.xml')
>>> simid = sim.createSimulation({'vLUE':3.2,'vSLA':0.023})
>>> sim.runSimulations()
>>> result = sim.getResult('YearlyOutput',simid)).toList()
>>> sim.closeProject()
>>> print(result['BiomassModule.Yield'])
805.45

class SimplaceClasses.SimplaceInstance(installDir=None, workDir=None, outputDir=None, projectsDir=None, dataDir=None, additionalClasspathList=[], javaParameters=None)[source]¶

Class to access and control the simulation Framework Simplace

closeProject()[source]¶: Close the project.

createSimulation(parameters=None, queue=True)[source]¶: Create a single simulation and set initial parameters.

getResult(output, simulation=None)[source]¶: Get a specific output of a finished simulation.

getSimplaceDirectories()[source]¶: get work-, output-, projects- and data-directory.

getSimulationIDs()[source]¶: Get the ids of ready to run simulations.

openProject(solution, project=None, parameters=None)[source]¶: Create a project from the solution and optional project file.

runProject()[source]¶: Run the project.

runSimulations(selectsimulation=False)[source]¶: Run created simulations.

setAllSimulationValues(parameterlist)[source]¶: Set values of all simulations in queue.

setCheckLevel(level)[source]¶: Set the checklevel of the solution.

setLogLevel(level)[source]¶: Set the log’s verbosity. Ranges from least verbose ‘ERROR’,’WARN’,’INFO’,’DEBUG’ to most verbose ‘TRACE’.

setProjectLines(lines)[source]¶: Set the line numbers of the project data file used for simulations.

setSimplaceDirectories(workDir=None, outputDir=None, projectsDir=None, dataDir=None)[source]¶: Set work-, output-, projects- and data-directory.

setSimulationValues(parameters)[source]¶: Set values of actual simulation that runs stepwise.

setSlotCount(count)[source]¶: Set the maximum numbers of processors used when running projects.

shutDown()[source]¶: Terminates the java virtual machine

stepAllSimulations(count=1, parameterlist=None, varFilter=None)[source]¶: Run al simulations in queue stepwise and return variable map list.

stepSimulation(count=1, parameters=None, varFilter=None, simulationnumber=0)[source]¶: Run specific simulation in queue stepwise and return variable map.

class SimplaceClasses.SimplaceResult(result)[source]¶

Result of a Simplace simulation. Returned by getResult() method.

getDatatypes()[source]¶: Get datatypes of the result values.

getUnits()[source]¶: Get units of the result values.

toList(expand=True, start=None, end=None)[source]¶: Return the result as python dictionary.

class SimplaceClasses.SimplaceVarmap(varmap)[source]¶

Actual Varmap from a simplace step run. Returned by step() method.

getUnits()[source]¶: Get units of the varmap values.

toList(expand=True)[source]¶: Return the varmap as python dictionary.

Troubleshooting¶

Simplace requires the packages JPype1 and numpy. If they are not installed automatically, try to install numpy and JPype manually.

For Windows you can use binary packages from http://www.lfd.uci.edu/~gohlke/pythonlibs/

You need also the Microsoft Visual C++ 2015 Redistributables. If they are not yet installed on your system, you have to do it manually.

Simplace needs a Java virtual machine. If you have 64 bit version of Python, then you need also the 64 bit version of Java.

If you get an error loading the java virtual machine, check if the java location is configured properly. There are different methods how python tries to detect the java virtual machine:

JAVA_HOME environment variable
Registry entry HKEY_LOCAL_MACHINE/SOFTWARE/JavaSoft/Java Runtime Environment/1.8[.xx]/RuntimeLib on Windows
the symbolic link /usr/lib/jvm/default-java on Ubuntu
…

Simplace’s documentation!¶

Procedural interface¶

Object oriented interface¶

Troubleshooting¶

Indices and tables¶

simplace

Navigation

Related Topics