Class FWSimEngine

java.lang.Object
net.simplace.sim.FWSimEngine

public final class FWSimEngine extends Object
Entry point of the simulation engine (singleton). It creates FWSimSessions from a solution file (.sol.xml) and an optional project file (.proj.xml), keeps the list of the current sessions and holds the global settings: work, output, data and projects directory, number of parallel slots, application mode and check level.

Typical use without GUI:

Without project file the solution is simulated once. With a project file the simulations are created by a plug-in FWSimulationGenerator and optionally selected by a FWSimulationSelector (see FWSimProject.PROJECT_MODE). The GUI uses call(int, String, HashMap, APPLICATION_MODE) with the action commands createSolution and run. Listeners are registered per session: FWSimulationListener at the session, FWSimOutputListener at its output manager.
Author:
Andreas Enders
  • Field Details

    • MAX_SIMULATION_COUNT

      public static int MAX_SIMULATION_COUNT
      maximum number of simulations the generator creates per chunk
  • Method Details

    • getInstance

      public static FWSimEngine getInstance()
      Returns the singleton instance and creates it if necessary. Not synchronized.
      Returns:
      the singleton instance
    • call

      public void call(int aClickCount, String aActionCommand) throws Exception
      Executes an action command in GUI mode without parameters, see call(int, String, HashMap, APPLICATION_MODE).

      Note: the parameter map is null here, which the called method does not handle (it fails with a NullPointerException).

      Parameters:
      aClickCount - click count of the mouse button (only logged)
      aActionCommand - action command
      Throws:
      Exception - if the action fails
    • call

      public void call(int aClickCount, String aFunction, HashMap<String, FWSimVariable<?>> aParameterMap, FWSimSession.APPLICATION_MODE aAppMode) throws Exception
      Executes an action command (controller of the GUI):
      • createSolution: prepares a session from the parameter map (parameter solution, see prepareSession(HashMap, Object[][], APPLICATION_MODE)); if the parameter go_on_automatically is true, the first current session is run afterwards
      • run: runs the first current session
      The parameter slotcount sets the number of parallel slots.
      Parameters:
      aClickCount - click count of the mouse button (only logged)
      aFunction - action command
      aParameterMap - parameters, may be null for run (createSolution then does nothing)
      aAppMode - application mode of the session to prepare
      Throws:
      Exception - if running the session fails; errors reading the solution are only logged
    • prepareSession

      public static FWSimSession prepareSession(String aProjectFileName, String aSolutionFileName) throws IOException
      Parameters:
      aProjectFileName - project file, or null to simulate the solution only
      aSolutionFileName - solution file
      Returns:
      the prepared session
      Throws:
      IOException - if the solution cannot be read
    • prepareSession

      public static FWSimSession prepareSession(String aProjectFileName, String aSolutionFileName, Object[][] aParameters) throws IOException
      Parameters:
      aProjectFileName - project file, or null to simulate the solution only
      aSolutionFileName - solution file
      aParameters - additional parameters passed to the session, may be null
      Returns:
      the prepared session
      Throws:
      IOException - if the solution cannot be read
    • prepareSession

      public static FWSimSession prepareSession(String aProjectFileName, String aSolutionFileName, FWSimSession.APPLICATION_MODE aApplicationMode) throws IOException
      Prepares a session in the given application mode, see prepareSession(String, String, Object[][], Integer[], APPLICATION_MODE).
      Parameters:
      aProjectFileName - project file, or null to simulate the solution only
      aSolutionFileName - solution file
      aApplicationMode - application mode
      Returns:
      the prepared session
      Throws:
      IOException - if the solution cannot be read
    • prepareSession

      public static FWSimSession prepareSession(String aProject, String aSolution, Object[][] aParameters, Integer[] aLinesToBeRead, FWSimSession.APPLICATION_MODE aApplicationMode) throws IOException
      Prepares a session for a solution and an optional project: creates the system parameters project, solution, project id (testproject), simulation id (testsimulation) and the project lines to read, and calls prepareSession(HashMap, Object[][], APPLICATION_MODE). Without project the solution is simulated once.
      Parameters:
      aProject - project file, or null to simulate the solution only
      aSolution - solution file name or solution XML content
      aParameters - additional parameters passed to the session, may be null
      aLinesToBeRead - lines of the project data to simulate, or null for all
      aApplicationMode - application mode
      Returns:
      the prepared session
      Throws:
      IOException - if the solution cannot be read
    • runProjects

      public static FWSimSession runProjects(String aProject, String aSolution, HashMap<String,String> aSplitMap)
      Prepares and runs a session and shuts the engine down afterwards. Without project the solution is simulated once.

      With a split map, one session is prepared and run per key; each key is a range of project lines (parsed with StringHelper.parseIntegerToArray(String, boolean)). Add ${sessionid} or ${projectid} to the output file names in that case, otherwise the outputs overwrite each other.

      Parameters:
      aProject - project file, or null to simulate the solution only
      aSolution - solution file
      aSplitMap - map whose keys are the project line ranges to run separately, or null to run all lines at once (values are not used)
      Returns:
      the (last) session that was run, or null if an error occurred (the error is logged)
    • runProjects

      public static FWSimSession runProjects(String aProject, String aSolution)
      Prepares and runs a session and shuts the engine down afterwards, see runProjects(String, String, HashMap).
      Parameters:
      aProject - project file, or null to simulate the solution only
      aSolution - solution file
      Returns:
      the session that was run, or null if an error occurred (the error is logged)
    • prepareSession

      public FWSimSession prepareSession(HashMap<String, FWSimVariable<?>> aParameterMap, Object[][] aParameters, FWSimSession.APPLICATION_MODE aApplicationMode) throws IOException
      Prepares a session from a parameter map. The parameter solution holds either the solution file name (tokens ${...} are replaced if the value is shorter than 256 characters) or the solution XML content.
      Parameters:
      aParameterMap - parameters, must contain solution
      aParameters - additional parameters passed to the session, may be null
      aApplicationMode - application mode
      Returns:
      the prepared session
      Throws:
      IOException - if the solution cannot be read or parsed
    • prepareSession

      public FWSimSession prepareSession(org.jdom2.Element aSolutionElement, FWSimVarMap aVarMap, Object[][] aParameters, String aSessionName, FWSimSession.APPLICATION_MODE aApplicationMode, FileData aSolutionFile)
      Creates a session from a parsed solution, adds it to the current sessions and sets the application mode of the engine.
      Parameters:
      aSolutionElement - root element of the solution
      aVarMap - variable map with the system parameters
      aParameters - additional parameters passed to the session, may be null
      aSessionName - name of the session (the solution file name)
      aApplicationMode - application mode
      aSolutionFile - the solution data (file or content)
      Returns:
      the created session
    • getCheckLevel

      public FWCheckHelper.CHECK_LEVEL getCheckLevel()
      Returns:
      the level the simulations are checked with while running, or null if not set
    • setCheckLevel

      public void setCheckLevel(FWCheckHelper.CHECK_LEVEL aCheckLevel)
      Parameters:
      aCheckLevel - the level the simulations are checked with while running
    • getCheckReport

      public FWCheckHelper.CHECK_REPORT getCheckReport()
      Returns:
      how violations of the runtime checks are reported, or null if not set (then project runs use SUMMARY and runs without project DETAIL, see FWSimSession.initProjects(net.simplace.sim.util.FWSimVarMap))
    • setCheckReport

      public void setCheckReport(FWCheckHelper.CHECK_REPORT aCheckReport)
      Sets how violations of the runtime checks are reported, for all sessions created afterwards (console option -checkreport).
      Parameters:
      aCheckReport - DETAIL (every violation), SUMMARY (counts at the end) or null (depends on the run, see getCheckReport())
    • setWorkDir

      public static void setWorkDir(String aPathString)
      Sets the work directory and creates it if it does not exist (errors are logged).
      Parameters:
      aPathString - path of the work directory
    • getWorkDir

      public static String getWorkDir()
      Returns the work directory. If not set, it defaults to SIMPLACE_WORK (relative to the current directory) outside the GUI, or to the setting SETTINGS.USER_CACHE in the GUI modes.
      Returns:
      the path of the work directory
    • setOutputDir

      public static void setOutputDir(String aPathString)
      Sets the output directory and creates it if it does not exist (errors are logged).
      Parameters:
      aPathString - path of the output directory
    • getOutputDir

      public static String getOutputDir()
      Returns the output directory. If not set, it defaults to SIMPLACE_WORK/output outside the GUI, or to the setting SETTINGS.USER_OUT in the GUI modes.
      Returns:
      the path of the output directory
    • setProjectsDir

      public static void setProjectsDir(String aPathString)
      Sets the projects directory and creates it if it does not exist (errors are logged as warning).
      Parameters:
      aPathString - path of the projects directory
    • getProjectsDir

      public static String getProjectsDir()
      Returns the projects directory. If not set, it defaults to the setting SETTINGS.USER_OUT.
      Returns:
      the path of the projects directory
    • setDataDir

      public static void setDataDir(String aPathString)
      Sets the data directory and creates it if it does not exist (errors are logged as warning).
      Parameters:
      aPathString - path of the data directory
    • getDataDir

      public static String getDataDir()
      Returns the data directory. If not set, it defaults to the setting SETTINGS.USER_OUT.
      Returns:
      the path of the data directory
    • registerSolution

      public static FWSimSession registerSolution(FWSimSolution aSolutionO, FWSimSession.APPLICATION_MODE aApplicationMode)
      Creates a session for an already created solution and sets the application mode of the engine. The session is not added to the current sessions (see registerSession(FWSimSession)).
      Parameters:
      aSolutionO - the solution
      aApplicationMode - application mode
      Returns:
      the created session
    • registerSession

      public static FWSimSession registerSession(FWSimSession aSessionO)
      Initializes the projects and outputs of a session and adds it to the current sessions.
      Parameters:
      aSessionO - the session, e.g. created by registerSolution(FWSimSolution, APPLICATION_MODE)
      Returns:
      the given session
    • shutDown

      public void shutDown()
      Finalizes all active sessions and discards the singleton instance, so the next getInstance() creates a new engine with default settings.
    • reset

      public static void reset()
      Discards the singleton instance without finalizing its sessions, so the next getInstance() creates a new engine.
    • getSlotCount

      public static int getSlotCount()
      Returns:
      number of simulations run in parallel (default: number of processors minus one, at least 2)
    • setSlotCount

      public static void setSlotCount(int aSlotCount)
      Parameters:
      aSlotCount - number of simulations run in parallel
    • setAppMode

      public static void setAppMode(FWSimSession.APPLICATION_MODE aAppMode)
      Parameters:
      aAppMode - application mode of the engine
    • getSessions

      public List<FWSimSession> getSessions()
      Returns:
      the current (not yet finalized) sessions; the live list, not a copy
    • finalizeSession

      public void finalizeSession(FWSimSession aCurrentSession)
      Finalizes a session (errors are logged) and removes it from the current sessions.
      Parameters:
      aCurrentSession - the session
    • getAppMode

      public FWSimSession.APPLICATION_MODE getAppMode()
      Returns:
      the application mode of the engine