Class SimplaceWrapper

java.lang.Object
net.simplace.sim.wrapper.SimplaceWrapper
Direct Known Subclasses:
JavaSimplaceWrapper

public class SimplaceWrapper extends Object
API to use the SIMPLACE engine from other applications and languages (R, Python, Julia, Matlab, Java; see JavaSimplaceWrapper and the language specific wrappers simplace for R and Python). It works with a single current session:
  1. create the wrapper with the directories
  2. prepareSession(String, String) with solution and optional project
  3. either run() for the whole project, or create simulations with createSimulation(Object[][]) and run them with runSimulations(boolean) or step by step with step() / stepAll()
  4. read the results of MEMORY outputs with getResult(String, String)
  5. shutDown() at the end
Parameters are passed as Object[][] of pairs {name, value}.

Limitation of several simulations created with createSimulation(Object[][]) (#465): they form one project. The resources (input data, transformers) are read once with the values of the first simulation, and file names of inputs and outputs (e.g. ${_WORKDIR_}/weather/${vLocation}.csv) are resolved once with them, too. So all simulations get the same input data and write into the same output files, even if a parameter used in a file name (like vLocation or projectid) differs. Model parameters (e.g. crop parameters, management dates) can differ freely. For different input data either run the simulations one after another (new prepareSession(String, String) or resetSimulationQueue() and runSimulations(boolean, boolean) with doUpdateResources), or use a project file with one line per location. createSimulation(Object[][]) logs a warning if a parameter occurs in a file name of an interface and differs from the first simulation.

Author:
Andreas Enders
  • Field Details

    • isSimulationInitialized

      protected boolean isSimulationInitialized
      if the simulations have been initialized (outputs, resources, generation)
    • iCurrentSession

      protected FWSimSession iCurrentSession
      the current (last prepared) session
    • iSimulationsQueue

      protected List<FWSimSimulation> iSimulationsQueue
      the simulations created or generated for stepwise or queued runs
    • iSimulationsCount

      protected int iSimulationsCount
      number of simulations created with createSimulation(Object[][]) (used as simulation number)
    • iInitializedSimulations

      protected List<Boolean> iInitializedSimulations
      per queue entry: if the simulation has been initialized
  • Constructor Details

    • SimplaceWrapper

      public SimplaceWrapper(String aWorkDir, String aOutputDir, String aProjectsDir, String aDataDir)
      Creates the wrapper and sets the directories of the engine (created if missing).
      Parameters:
      aWorkDir - work directory
      aOutputDir - output directory
      aProjectsDir - projects directory, or null for the work directory
      aDataDir - data directory, or null for the work directory
    • SimplaceWrapper

      public SimplaceWrapper(String aWorkDir, String aOutputDir)
      Creates the wrapper and sets work and output directory; projects and data directory are the work directory.
      Parameters:
      aWorkDir - work directory
      aOutputDir - output directory
    • SimplaceWrapper

      public SimplaceWrapper()
      Creates the wrapper without setting directories. Only for test classes and for further wrappers in the same process after the directories were set once (e.g. one wrapper per REST session); otherwise give work and output directory.
  • Method Details

    • setDirectories

      public void setDirectories(String aWorkDir, String aOutputDir, String aProjectsDir, String aDataDir)
      Sets the directories of the engine; null leaves a directory unchanged.
      Parameters:
      aWorkDir - work directory, may be null
      aOutputDir - output directory, may be null
      aProjectsDir - projects directory, may be null
      aDataDir - data directory, may be null
    • getDirectories

      public String[] getDirectories()
      Returns:
      the directories of the engine: work, output, projects and data directory
    • prepareSession

      public FWSimSession prepareSession(String aProject, String aSolution)
      Prepares a session for solution and project and makes it the current session. Then run() runs it, or the simulations can be stepped (see step()).
      Parameters:
      aProject - project file, or null to run the solution only
      aSolution - solution file
      Returns:
      the new session, or the previous one if the files cannot be read (the error is logged)
    • prepareSession

      public FWSimSession prepareSession(String aProject, String aSolution, Object[][] aParameterMap)
      Prepares a session for solution and project with additional parameters and makes it the current session (see prepareSession(String, String)). The project lines set before are used.
      Parameters:
      aProject - project file, or null to run the solution only
      aSolution - solution file
      aParameterMap - parameters as pairs {name, value} overriding solution variables, may be null
      Returns:
      the new session, or the previous one if the files cannot be read (the error is logged)
    • run

      public void run() throws Exception
      Runs all projects of the current session (see FWSimSession.run()); the session is finalized afterwards.
      Throws:
      Exception - if the run fails
    • run

      @Deprecated public void run(String aProjectlines) throws Exception
      Runs all projects of the current session.

      The project lines cannot be applied here, as the project data are already read when the session is prepared; a given value is ignored with a warning. Use setProjectLines(String) before prepareSession(String, String) and then run().

      Parameters:
      aProjectlines - project lines as string (e.g. "1,2,5,9-100"), ignored
      Throws:
      Exception - if the run fails
    • createSimulation

      public FWSimSimulation createSimulation(Object[][] aParameterMap) throws Exception
      Creates a simulation of the current session with the given parameters and adds it to the queue, so several simulations can be run together (see runSimulations(boolean)). Only solution variables should be passed. All simulations of the queue use the input data and output files of the first one (see the class description); a warning is logged once per parameter if a parameter used in a file name of an interface differs from the first simulation.
      Parameters:
      aParameterMap - parameters as pairs {name, value}, may be null
      Returns:
      the created simulation
      Throws:
      Exception - if a value cannot be set
    • runSimulations

      public void runSimulations(boolean doSelectSolution, boolean doUpdateResources) throws Exception
      Runs all simulations of the queue (created with createSimulation(Object[][])) and clears the queue. On the first call (or with doUpdateResources) the output writers are started and the project is generated; the resources are updated with the first simulation.
      Parameters:
      doSelectSolution - if a selection should be done (passed on, currently not used)
      doUpdateResources - true to initialize again before running
      Throws:
      IllegalStateException - if the queue is empty
      Exception - if running fails
    • runSimulations

      public void runSimulations(boolean doSelectSolution) throws Exception
      Runs all simulations of the queue, see runSimulations(boolean, boolean).
      Parameters:
      doSelectSolution - if a selection should be done (currently not used)
      Throws:
      Exception - if running fails
    • initializeSpecificSimulation

      public void initializeSpecificSimulation(int aSimulationQueueIndex)
      Initializes a simulation of the queue before its parameters are set or it is stepped; on the first call all simulations are initialized first (see initSimulations()).
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
    • resetSimulationQueue

      public void resetSimulationQueue()
      Clears the queue of simulations and the result caches of the memory outputs.
    • getSimulationIDs

      public String[] getSimulationIDs()
      Returns:
      the ids of all simulations in the queue
    • getResult

      public DataContainer getResult(String aName, String aSimulationID)
      Returns the results of a MEMORY output after the simulations have been run.
      Parameters:
      aName - name of the output (must use a MEMORY interface)
      aSimulationID - id of a simulation, or null for all simulations
      Returns:
      the data, or null if there is no output with this name or it is no memory output (the error is logged)
    • setSimulationValues

      public void setSimulationValues(int aSimulationQueueIndex, Object[][] aParameterMap)
      Sets values in the variable map of a simulation of the queue (initializing it first if necessary). An invalid index is ignored.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - values as pairs {name, value}
    • setSimulationValues

      public void setSimulationValues(Object[][] aParameterMap)
      Sets values in the variable map of the first simulation of the queue.
      Parameters:
      aParameterMap - values as pairs {name, value}
    • setSpecificSimulationValues

      public void setSpecificSimulationValues(int aSimulationQueueIndex, Object[][][] aParameterMap)
      Sets the values for one simulation from a list of value maps (one per simulation).
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - one array of pairs {name, value} per simulation
    • setAllSimulationValues

      public void setAllSimulationValues(Object[][][] aParameterMap)
      Sets the values of all simulations of the queue.
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, Object[][] aParameterMap, String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs a simulation of the queue stepwise: sets the values, calculates the given number of steps and returns the variable map after the last step. On the first call outputs, resources and project are initialized. When the simulation ends, it is finished (once) and null is returned; further calls return null without calculating (unlike stepAll(Object[][][], String[], int, boolean), which returns the last state marked with DataContainer.isLast()). With a step count of 0 only the values are set and the current state is returned.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - values as pairs {name, value} set before the steps, may be null
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended or the index is invalid
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, int aStepCount) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, String[] aOutputFilterArray) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, Object[][] aParameterMap) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - values as pairs {name, value} set before the steps
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, Object[][] aParameterMap, int aStepCount) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - values as pairs {name, value} set before the steps
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • stepSpecific

      public DataContainer stepSpecific(int aSimulationQueueIndex, Object[][] aParameterMap, String[] aOutputFilterArray) throws Exception
      Runs a simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aSimulationQueueIndex - index of the simulation in the queue (0-based)
      aParameterMap - values as pairs {name, value} set before the steps
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(Object[][] aParameterMap, String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - values as pairs {name, value} set before the steps
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step() throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(int aStepCount) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(String[] aOutputFilterArray) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(Object[][] aParameterMap) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - values as pairs {name, value} set before the steps
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(Object[][] aParameterMap, int aStepCount) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - values as pairs {name, value} set before the steps
      aStepCount - number of steps to calculate
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • step

      public DataContainer step(Object[][] aParameterMap, String[] aOutputFilterArray) throws Exception
      Runs the first simulation of the queue stepwise, see stepSpecific(int, Object[][], String[], int). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - values as pairs {name, value} set before the steps
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      the variables after the steps, or null if the simulation has ended
      Throws:
      Exception - if a step fails
    • initSimulations

      public void initSimulations() throws Exception, MissingSimResourceException
      Initializes the simulations for stepwise runs: if the queue is empty, the simulations of the first project are generated and put into the queue; then the simulations are registered at the outputs, the output writers are started and the resources are updated.
      Throws:
      Exception - if generating or initializing fails
      MissingSimResourceException - if a resource is missing
    • stepAll

      public DataContainer[] stepAll(Object[][][] aParameterMap, String[] aOutputFilterArray, int aStepCount, boolean aParallelized) throws Exception
      Runs all simulations of the queue stepwise: for each simulation the values are set, the given number of steps is calculated and the variable map is returned. A simulation that ends is finished (once) and its result is marked as last (DataContainer.setLast(boolean)); it is not calculated beyond its end date, further calls return its last state again, marked as last.
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation, may be null
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      aParallelized - true to step the simulations in parallel, with at most getSlotCount() threads (like a normal run); the results and outputs are the same as stepping them one after another
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(Object[][][] aParameterMap, String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs all simulations of the queue stepwise, not in parallel, see stepAll(Object[][][], String[], int, boolean).
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation, may be null
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll() throws Exception
      Calculates one step of all simulations of the queue, see stepAll(Object[][][], String[], int, boolean).
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(int aStepCount) throws Exception
      Calculates steps of all simulations of the queue, see stepAll(Object[][][], String[], int, boolean).
      Parameters:
      aStepCount - number of steps to calculate
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(String[] aOutputFilterArray) throws Exception
      Calculates one step of all simulations of the queue, see stepAll(Object[][][], String[], int, boolean).
      Parameters:
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(String[] aOutputFilterArray, int aStepCount) throws Exception
      Runs all simulations of the queue stepwise, see stepAll(Object[][][], String[], int, boolean). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aOutputFilterArray - names of the variables to return, or null for all
      aStepCount - number of steps to calculate
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(Object[][][] aParameterMap) throws Exception
      Runs all simulations of the queue stepwise, see stepAll(Object[][][], String[], int, boolean). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(Object[][][] aParameterMap, int aStepCount) throws Exception
      Runs all simulations of the queue stepwise, see stepAll(Object[][][], String[], int, boolean). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation
      aStepCount - number of steps to calculate
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • stepAll

      public DataContainer[] stepAll(Object[][][] aParameterMap, String[] aOutputFilterArray) throws Exception
      Runs all simulations of the queue stepwise, see stepAll(Object[][][], String[], int, boolean). Omitted arguments mean: no values set, all variables returned, one step.
      Parameters:
      aParameterMap - one array of pairs {name, value} per simulation
      aOutputFilterArray - names of the variables to return, or null for all
      Returns:
      one result per simulation
      Throws:
      Exception - if the initialization fails
    • registerOutputListener

      public void registerOutputListener(FWSimOutputListener aOutputListener)
      Registers a listener that is notified on every output call of the current session.
      Parameters:
      aOutputListener - the listener
    • removeOutputListener

      public void removeOutputListener(FWSimOutputListener aOutputListener)
      Removes an output listener.
      Parameters:
      aOutputListener - the listener
    • registerModelListener

      public void registerModelListener(FWSimulationListener aModelListener)
      Registers a listener for the simulation, project and iteration events of the current session.
      Parameters:
      aModelListener - the listener
    • removeModelListener

      public void removeModelListener(FWSimulationListener aModelListener)
      Removes a simulation listener.
      Parameters:
      aModelListener - the listener
    • shutDown

      public void shutDown()
      Finalizes the current session (writes remaining outputs, closes files) and clears the queue and the project lines; has to be called at the end. Errors are logged.
    • setCheckLevel

      public void setCheckLevel(String aCheckLevel)
      Sets the check level of the engine; to be called before preparing a session.
      Parameters:
      aCheckLevel - name of the check level: OFF, LAZY, INTENSE, STRICT, CUSTOM or ONLY
    • setLogLevel

      public static void setLogLevel(String aLogLevel)
      Sets the log level of the whole process (static, applies to all sessions). Language bindings should use this method instead of accessing the logger directly.
      Parameters:
      aLogLevel - name of the log level, from least to most verbose: FATAL, ERROR, WARN, INFO, DEBUG, TRACE (case insensitive)
      Throws:
      IllegalArgumentException - if the name is not a log level
    • setSlotCount

      public static void setSlotCount(int aSlotCount)
      Sets the maximum number of simulations run in parallel, i.e. the number of processor cores used (static, applies to all sessions). Language bindings should use this method instead of accessing the engine directly.
      Parameters:
      aSlotCount - number of parallel simulation slots, at least 1
      Throws:
      IllegalArgumentException - if the count is less than 1
    • getSlotCount

      public static int getSlotCount()
      Returns:
      the maximum number of simulations run in parallel (see setSlotCount(int))
    • setProjectLines

      public void setProjectLines(String aProjectLines)
      Sets the lines of the project data to read; to be called before preparing a session.
      Parameters:
      aProjectLines - lines as string, e.g. "1,2,5,9-100"
    • setProjectLines

      public void setProjectLines(Integer[] aProjectLines)
      Sets the lines of the project data to read; to be called before preparing a session.
      Parameters:
      aProjectLines - the line numbers, or null for all