SPARK latest release v2.01-031113 - Last updated 13 November 2003.  
 

Release 2.01 (Build 031113)

Changes

  • VisualSPARK GUI:
    • Changed labels in Component Preference Editor in the inverse and variable trees to shorter and more user-readable names. Internal type names were used in the previous release.
  • setupcpp:
    • Changed the naming scheme for the inverses in the atomic classes. Now each inverse name is prefixed with the list of the target port(s) associated with it to make it unique.
  • solver library:
    • Modified output of diagnostic mechanism to run log file:
      • "Show inputs" mode now shows the name of the variable used in the INPUT_FROM_LINK statement.
      • "Show inputs" mode now shows the name of the variable used in the PREDICT_FROM_LINK statement defined for the break variables.
      • "Show reports" mode no longer displays the simulation step stamp at each step.
    • Improved error diagnostic in input files by keeping track of the line count.
    • Renamed the namespace SPARK::Callback as SPARK::AtomicClass in the file classapi.h where the data managements functions are implemented.
    • The method TProblem::SaveTrajectory() is deprecated and replaced with TProblem::Save().
    • The method TProblem::LoadTrajectory() is deprecated and replaced with TProblem::Restore().
    • Renamed the enum type TProblem::SimulatorStates as TProblem::SimulationFlags to avoid name conflict with the newly defined state mechanism defined as TProblem::TState.
    • Defined SPARK::Log() API function to write messages from atomic classes to any output stream. Supercedes the now deprecated SPARK::WriteToErrorLog() API function.

New features

  • Added the key CheckBadNumericsFlag in the the component section of the preference settings file. When set to 1 the nonlinear solver will perform a more robust treatment by detecting bad numerics (NaN and infinte values) in the inner loop of the solution method. By default the flag is set to 0 and the strategy is not used by the solver because it is computationally very expensive.
  • Added the "View log file" button in the Run window. It will pop up a file browser dialog to allow the user to view one or more log files in the standard VisualSPARK text editor window (read-only).
  • Added high-level simulation primitives to the driver API to facilitate the implementation of the driver functions.
  • Added support for the meta-character '*' in input files in place of a time stamp to specify values that are valid until infinity. Typically, constant values should be specified using this '*' time stamp to indicate that they remain unchanged for the entire duration of the simulation.
  • Added support for C-style comments in input files, preference files and run-control files.
  • Re-implemented native input stream mechanism with random-access capability.
  • Added support for the meta-character '*' used in place of a scalar value when specifying the final time in the *.run file. This essentially means that the simulation will run until "infinity", unless a stop or abort request is triggered or the simulation fails.
    ( 
      InitialTime ( 0 ()) 
      FinalTime   ( * ())
      ...
    )
    
  • Added new GET_DATA, SET_DATA and DELETE_DATA macros in the file spark.h to automatically perform the type casting operations when handling the private data attached with each inverse and object ina an atomic class.
    STATIC_CONSTRUCT( SomeStaticCallback )
    { 
      TStaticData* MyStaticData = new TStaticData( ... );
      ...
      // Equivalent to:  THIS->SetData( MyStaticData ) ;
      SET_DATA( TStaticData, MyStaticData );
    }
    EVALUATE( SomeInstanceCallback )
    { 
      // Equivalent to:  TData* MyData = static_cast<TData*>( THIS->GetData() );
      GET_DATA( TData, MyData );
      MyData->DoSomething();
      ...
    }
  • Added the class TProblem::TState to describe the problem state that can be saved at the current time by invoking TProblem::Save(). A TProblem object can also be restored to a saved state by calling the TProblem::Restore() method. For now, the class private data is not saved along with the trajectory. Therefore, restoring the problem state does not bring the TProblem object exactly to its original state at the time of the call to TProblem::Save() if class private data changed in the meantime.
  • Added a new key in the preference file used by the setupcpp program to specify the name of a single library for all callbacks referenced in the problem. This allows to package all compiled atomic classes in a single DLL instead of defining a single DLL for each atomic class (default behavior). For example, the following entry in the setupcpp preference file will use libechiller as the library name in the generated XML file for the <function> elements.
    (
      ...
      LibraryName ( libechiller () )
      ...
    )

Bug fixes

  • Fixed compiler idiosyncrasies occurring with MS VC++ 6:
    • Solver library sent a runtime exception when writing to the log std::ostream objects (i.e., the run log file and the error log file) from an atomic class.
    • Solver library did not export the necessary symbols in order to be able to call the methods of the TVariable class to get and set the current values.
  • solver library:
    • The linesearch backtracking strategy for the step control in the nonlinear solver did not detect convergence due to a zero cost function. This forced the solver to recover with other iterative methods, which was time-consuming and not necessary.
    • Timer object in solver library did not operate correctly when making successive calls to the TProblem::Simulate() method with the same TProblem object.
    • Variables defined with the INPUT_FROM_LINK=fromLink statement in the problem specification did not show the same past values as the fromLink variable.
    • Fixed bug occurring in variable time stepping mode caused by the bad detection of the next time stamp event.
  • VisualSPARK GUI:
    • M-link variables could not be shown in the tree widget in the component preferences editor.
    • Command name in table binding for carriage return in input table changed from tkTableMoveCell to ::tk::table::MoveCell in tkTable 2.8.
    • Busy cursor wasn't restored to normal cursor if user tried to create set file that already existed.
    • Show version number and build number in About box of VisualSPARK.
    • Run button wasn't being activated in Run Window by default.
    • Time-varying table titles showed cursor when selected (implied editable)
    • Red/Yellow text in input panel changed to: "Variable names in RED are in .pr file but not in data set file, variables in YELLOW are unknowns".
    • Upper X axis wasn't working for plots with single variable.
    • Two typos in comparison plot dialog prevented functioning.
    • XML file was being moved from project directory to set directory, causing unnecessary recompilation of the executable in some cases. Solution is to copy the XML file instead of moving it.
    • Run window wasn't being destroyed when user changed projects.
    • Units may have been incorrect for break and dynamic variables in input panel.
    • Several values weren't restored when "Restore Initial Values" was pressed in Run Window.

Release 2.00 (Build 030701)

Changes

  • SPARK language:
    • The keyword PRED_FROM_LINK is deprecated and replaced by PREDICT_FROM_LINK.
    • The callback type keyword PRED is deprecated and replaced by PREDICT.
    • The callback type keyword EVAL is deprecated and replaced by EVALUATE.
  • parser and setupcpp programs:
    • Added a new block to the beginning of the .stp file that contains the class data of the problem.
    • Updated the .cpp file generated by setupcpp to build a self-contained, compiled problem simulator, with preprocessor macros hiding the implementation details.
    • Added sections for global settings and default component settings in the default.prf file and in the problem preference file.
    • Changed the syntax used to implement the callback functions in the atomic classes.
  • solver library:
    • All C++ classes and functions in solver are now defined within the SPARK namespace.
    • The method TProblem::InitialSolve() has been decommissioned because the solution process now depends on the current state of the simulator. The method TProblem::Solve() has thus been renamed TProblem::Simulate(), which returns a code that indicates whether the simulation succeeded or failed.
    • Discontinued UpdateSettingsAtRuntime key in the .prf file because the update mechanism has been decommissioned.
    • Extended diagnostic mechanism to run log file to show preference settings, reports, requests, and statistics.
  • Global classes and HVAC Toolkit:
    • The old-style integrator class abm.cc in globalclass has been renamed abm4.cc to indicate its integration order.
    • Ported all atomic classes in globalclass and hvactk directories to support the new class syntax for the EVALUATE callback functions.
  • Added multi-compiler support through parametrizable makefiles:
    • Windows: VC++ 6-.NET and g++ 2.95-3.2
    • UNIX/Linux: g++ 3.2
  • VisualSPARK Input window:
    • Min and max removed because they are available in preference editor (problem structure with variable list).
    • Run information moved from input panel to its own window. "time increment" renamed to "constant time step" if VariableTimeStep set to 0 in .run file (mode off). "time increment" renamed to "initial time step" if VariableTimeStep set to 1 in .run file (mode on).
  • VisualSPARK Preference editor:
    • Tolerance and max tolerance moved from component tabs to global tab.

New features

  • Added the new language keyword CLASSTYPE to identify the type of each atomic class in the .cc files. Typing the atomic classes allows to provide special behavior for these classes during the graph analysis and/or the numerical solution phase at runtime. Supported class types are: DEFAULT, SINK and INTEGRATOR.
  • Added native support for new inverse types:
    • Multi-valued inverses are assigned to more than one port and return their respective values simultaneously. A current limitation of the graph analysis prevents defining more than one multi-valued inverse per atomic class.
    • Residual inverses are specified using the RESIDUAL keyword after the equal sign in the FUNCTIONS {} block. Unlike default inverses in explicit form that return the values of the target ports, residual inverses return the residual values for the equations assigned to each target port.
    • Default residual inverses are single-valued residual inverses defined at the class level with the DEFAULT_RESIDUAL keyword. They define the default residual inverse to be used when no other inverse satisfies the matching requirements.
  • Extended callback framework with a set of instance and static callback functions. Each callback function is specified by using the keyword for the function type next to the function's name in the FUNCTIONS {} block. The callback functions can be categorized into 3 groups: modifiers, structors, non-modifiers and predicates.
  • Added mechanism to attach private data to each inverse. Private data can then be retrieved from within each callback function using the SPARK macros. We distinguish between instance data that is specific to each instance of the inverse and static data that is shared by all instances of the same inverse.
  • Added request mechanism to send runtime requests from the callback functions to influence the behavior of the simulator. Defined requests to synchronize the solver with meeting points, to restart the simulation by solving a static step, to generate a report or a snapshot file at the current time, and to abort the simulation.
  • The problem topology is now described by an XML file. This allows having a compiler- and linker-free SPARK as long as all atomic classes are compiled and built as dynamic libraries.
  • Solution methods:
    • Integrated newest release of UMFPACK for sparse linear solver (version 4.0).
    • Added perturbed Newton solution method.
    • Added variable scales for all problem variables.
  • Preference settings:
    • Added keys in .prf file for safety factors used in convergence test (for Prediction/Iteration stage and Break/Normal unknown variables).
    • Added a key in .prf file to specifiy the minimum number of iterations to perform when solving the strong components.
    • Added a new section GlobalSettings in .prf file with tolerance settings, convergence check settings and user-defined settings.
    • Added a new DefaultComponentSettings section in .prf file that defines the default values for the component settings that will be used if no value is specified for the setting in the component in question.
    • Changed the propagation rule for preferences across components. Now, if no value is specified for a setting, then the value from the default component settings will be used.
  • Added the following new keys in the .run file:
    • InitialConsistentCalculation to indicate whether or not to calculate consistent values at the initial time by solving for the time-derivatives of the dynamic variables using the specified boundary conditions.
    • InitialTimeStep to specifiy the value of the initial time step.
    • VariableTimeStep to indicate whether or not to vary the time step during the simulation.
    • MinTimeStep to specifiy the smallest allowed time step.
    • MaxTimeStep to specifiy the largest allowed time step.
  • New driver API:
    • Now supports both static and dynamic problem build operations in the driver function
    • The runtime problem loader now supports explicit linking from dynamic libraries.
    • Implemented new API functions to facilitate the integration of the SPARK solver in an external driver function, thus making it easier to use SPARK as a simulation kernel.
  • Extended SPARK input mechanism with the URL mechanism. This is a generalized way of specifying where and how input values are to be obtained at runtime. It is string-based and extensible to support more URL handlers. Implemented URL handlers:
    • DOE-2, TMY and EnergyPlus weather files
    • DOE-2 schedules
    • algebraic expressions
    • ASCII formatted files
  • Global classes and HVAC Toolkit:
    • Defined framework of C++ classes to describe predictor-corrector integration methods supporting variable time stepping operation and control of the local trcunation error. Implemented the Euler and Trapezoidal integration schemes as global atomic classes usingthe integration framework.
    • Added the atomic class robust_square.cc that uses the RESIDUAL inverse mechanism. This class describes a numerically robust square root relation that deals with the infinitely large partial derivative when the dependent variable approaches zero.
  • VisualSPARK Main window:
    • Class tree-view of problem, macro class or atomic class. Can show as class names or object names. Can be printed on PostScript printer.
    • Classes window cleared only when user clicks on project that doesn't have current class directory in its class path. Old behavior was to clear the classes window when the user clicked on any project, even current.
    • Right-clicking on project name pops up a menu from which the user may choose to edit the problem file or show the tree structure of the problem.
    • Right-clicking on a class name pops up a menu from which the user may choose to edit the class file or show the tree structure of the class.
  • VisualSPARK Input window:
    • Initial predictor values for the break variables and initial values for dynamic variables may be entered in input panel in their own tabs.
    • Read URLs may be entered in input panel in constant/url section.
    • Read URLs in problem file shown in input panel in constant/url section with red text on light blue background.
    • Buttons at top of input panel to create or raise Main window, Input window, Graph window and Run window.
    • If changes are made to input window and user tries to close Main VisualSPARK window, confirmation dialog pops up to ask user if he/she wants to save or discard the data or cancel the quit.
    • Variables sorted alphabetically.
  • VisualSPARK Run window:
    • Checkbox to allow variable time step and inputs for mininum and maximum time step.
    • Checkboxes to show multiple diagnostics: Convergence, Inputs, Reports, Preferences, Statistics and Requests.
    • Wallclock entries to choose date and time for run (e.g. for reading weather file data).
  • VisualSPARK Graphs:
    • Comparative plots of related problems - can show same variables from multiple runs of problems on same graph.
    • Grid lines for either X and Y axes.
    • "Smart Symbols" changed to "Maximum number of symbols" to reduce clutter when curves have many data points. Symbols are evenly spaced with no more than the maximum number (settable by user) appearing on curves.
    • The "Make Graph" button is not active until one or more variables have been chosen to graph.
  • VisualSPARK Preference editor:
    • Added new Structure tab showing problem structure as tree from the XML file in the first tab. User may browse inverses, parameters, input variables and unknowns.
    • Added new Defaults tab showing the default values for solution methods, max iterations, etc. that are used in the components if the user doesn't override them.
    • Added new Globals tab showing the values global to the problem, namely Tolerance and Max Tolerance.
    • Component tab shows component structures as trees, where users may browse unknowns and objects, including their inverses, targets and callbacks.
    • Added entry for the new matrix solver Sparse LU, from UMFPACK version 4.0 in component settings.
  • VisualSPARK Miscellaneous:
    • More words highlighted in error message window when compiling/running problem. The words "undefined", "multiple definition" are now highlighted in addition to "error".
    • Wheelmouse scrolling added to all scrollable areas.
    • "Modify Class Path" window allows changing the class path for current project/problem, current projects or all SPARK problems.

Bug fixes

  • VisualSPARK GUI:
    • Bug fixed in tracking input panel editing to know when the user has made changes so that they may be asked if they want to save when closing input panel.
    • Better recovery when CLASSPATH is incorrect.
    • Scaling method options in preferences have been reduced to "No scaling" and "Full scaling" to reflect actual state of the solver.
    • Fixed bug in version 1.02 with autoscaling in graphs. After using manual scaling, switching back to autoscaling had no effect. Also in manual scaling, if the value for the minimum axis label was larger than for the maximum it would fail in a way that required the user to close and open the graphing window again.
    • If there was no UNITS line in an output file the program would crash.

Release 1.02 (Build 021205)

Changes

  • Documentation:
    • Merged glossary of terms between the "SPARK Reference Manual" and the "VisualSPARK Users Guide".
    • Enforced text conventions throughout the documentation to better distinguish the different elements of the SPARK language.
  • SPARK language:
    • Discontinued usage of the keyword UPDATE_FROM_LINK in LINK, PORT and PROBE statements and replaced it with the keyword INPUT_FROM_LINK that better reflects its behavior.
  • solver library:
    • Improved convergence strategy by performing the convergence check in the variable space, i.e. solely based on the increments value, after the first iteration.
    • Discontinued the AbsTolerance keyword previously specified in the problem.prf file at the component level. Absolute tolerance is now specified individually for each problem variable using the ATOL keyword.
  • VisualSPARK GUI:
    • Changed default wall clock settings to year 2002.
    • Changed title of button from "Modify" to "Modify Class Path".
    • Added support for new solver features in the component preferences editor.
    • The absolute tolerance entry has been removed from the component preferences editor because it is now specified on a variable-by variable basis.
    • Added the sparse LU matrix solving method.
    • Reduced scaling types to "None" and "Full" in place of the former scaling options in VisualSPARK 1.01.

New features

  • Added support for default values for the component preferences specified in a file called default.prf and residing in the work directory. The default values are used to populate the template preference file associated with the solution sequence generated by setupcpp for the problem.
  • Added a new variable property ATOL to the SPARK language on the PROBE, PORT and LINK statements in order to specify the absolute tolerance for each problem variable. The ATOL property should be set to the absolute value at which the variable in question is essentially insignificant.
  • Improved the input handler to allow to read in properties of problem variables along with the variable values at the specified time stamps. For example, the syntax to specify the property ATOL of the variable X is the qualified name X:ATOL. The input handler can read in values for any variable properties, namely MIN, MAX, ATOL and INIT.
  • Solution methods:
    • Added sparse linear solution method based on the C library UMFPACK (version 3.2) by Tim Davis. It does not rely on vendor specific BLAS routines but instead on vanilla C code, thus ensuring portability of the SPARK program. Drastic gains in calculation speed by many order of magnitudes have been observed on large problems for which the Jacobian matrix is typically more than 90% sparse.
    • Replaced previous scaling schemes with a single scaling scheme that achieves fully affine invariant scaling in both the variable space and residual space.
    • Added automatic Jacobian refresh strategy to ensure robust and fast convergence. The refresh strategy is based on the convergence behavior of weighted residual and increment norms between successive iterations.
  • Statistics log file generated at the end of the simulation containing performance statistics about the solver operation.
  • Implemented basic problem driver API to manage and solve multiple problems, access and modify the problem variables, and change run-control settings.

Bug fixes

  • Corrected typo in description of the macro links in the Reference Manual where the single quote ' used to prefix an object name in a hierarchy of objects was replaced with the single quote ` as prescribed by the SPARK syntax.
    	obj1'obj2'obj3~linkname
    
    bas been replaced with
    	obj1`obj2`obj3~linkname
    
  • parser program:
    • Keyword PARAMETER did not work when there were more than one PARAMETER statement in one class.
    • Fixed infinite loop bug caused by aliased variables. Aliased variables are created in LINK statements that do NOT contain obj.port connections.
  • Detect wrong calling syntax when calling the setupcpp program and write proper command-line usage to the screen instead of crashing.
  • Fixed bug in the sparksym program for the mathomatic symbolic solver that limited to 14 the number of variables allowed in the equation to be processed.
  • Fixed bug in runtime problem loader caused by reserved delimiters ",[]" appearing in the unit string of a variable.

Release 1.01 (Build 020510)

Changes

  • SPARK language
    • The LINK statement can now create a variable without specifying any connections.
    • The PORT statement has a new keyword of the form LIKE=anotherPortName. This copies the properties (including the subports) of the port named 'anotherPortName', to the port currently being defined.
  • Modified the format of the .cpp file generated by setupcpp to support the runtime loading scheme. See changes to solver for more details.
  • solver library:
    • Modified the scaling scheme to use the absolute value of the break variable instead of the arithmetic mean of the value of the break variable and of the value returned by the inverse associated with the break variable. Thus, the residual norm is no longer limited to a maximum value of 2. This new scaling scheme also improves the line-search backtracking step control.
    • The time units of the GLOBAL_TIME and GLOBAL_TIME_INCREMENT links are now overriden with the corresponding unit strings specified in the problem run file. This allows the correct units to be displayed in the header portion of the output, trace and snapshot files.
    • The SPARK library functions defined in the file spark.h are now declared as part of the SPARK namespace. This is to avoid potential name collision with user-defined functions in the atomic classes.
  • VisualSPARK GUI:
    • Version number now appears in all window title bars.
    • Layout of the Component Preference Editor has been changed to a more logical format with parts enabled only when they are allowable.
    • Graph lines are now thicker to improve visibility.
    • On graphs, curves that are mapped to the Y2 axis are grouped after curves mapped to the Y1 axis are in the legend.
    • Yellow curve color has been changed to gold for visibility.
    • The run log file now pops up in addition to the error.log file if there is a run-time problem while running the solver.
    • The class directory name for the current project has been changed from "." to ". (project)".

New features

  • New examples have been added to the tutorial.
  • solver library:
    • A runtime loading scheme has been added to solver in order to load the problem description contained in the .cpp file at runtime, during startup, as opposed to during the compilation step. This overcomes a compiler limitation that was encountered with large SPARK problems and also provides a faster way of loading problems during the problem testing phase.
    • Input files are now checked at runtime to make sure that the time stamps for the input values are specified in increasing order.
  • VisualSPARK GUI:
    • Balloon messages have been added to the Component Preference Editor.
    • Multiple trace files are now allowed, one for each trace type.
    • Time units have been added to the X-axis title on graphs.
    • Multiple units (e.g. "[W, deg C]" ) have been added to Y-axis titles on graphs.

Bug fixes

  • In the computation of the Secant method, fixed a bug that was returning a constant positive value for any negative partial derivative.

Release 1.00 (Build 010104)

Changes (since beta 0.91 version)

  • Changed the format of the .run file to use the same syntax as the .prf file.
  • Changed the command-line usage of the SPARK solver whereby the names of the .run file and of the .prf file must be specified following the name of the executable simulator.

New features (since beta 0.91 version)

  • Added diagnostic mechanism that writes convergence information and reports to the run log file.
  • Added the key InitialSnapshotFile and FinalSnapshotFile to the .run file to specifiy the names of the snapshgot files to be generated after the initial time calculation and after the last simulation step.
  • Implemented a mixed relative/absolute tolerance requirement in the convregence check of the nonlinear solver.
  • Added automatic scaled perturbation mode to compute the finite-differences in the .prf file.
  • Implemented runtime update of the component settings by re-parsing the .prf file whenever its date stamp changes.