Upgrade to SysCAD 9.3

From SysCAD Documentation
Jump to: navigation, search

Navigation: User Guide -> Upgrade to SysCAD 9.3

Related Links: SysCAD 9.3 Release Notes, SysCAD 9.3 Tag Changes, Crypkey Version 8, Upgrading Builds


In the majority of cases, a project from SysCAD 9.2 Build 135 will upgrade relatively smoothly to SysCAD 9.3 Build 136. It is strongly recommended to upgrade from a converged SysCAD 9.2 Build 135 project (preferably the most recent Build 135). It is expected that an upgraded project will give the same results as the original converged 135 project.

For projects in a very old version of SysCAD it is recommended that a user upgrades projects in a step wise fashion. For example, if the user currently has SysCAD 9.1 project, then it is advisable to upgrade to SysCAD 9.2 before finally upgrading to SysCAD 9.3.

For a full list of new functionality in SysCAD 9.3 and differences between SysCAD 9.2 and SysCAD 9.3, please refer to SysCAD 9.3 Release Notes.

Installing SysCAD 9.3

  1. Install SysCAD 9.3. This should be installed to a new location, by default this will be \SysCAD93. Note that administrator rights are required to install this correctly.
  2. The installation will include Crypkey8 license Service that is used in SysCAD 9.3.
  3. The installation includes an install of the latest "Microsoft Visual C++ Redistributable Package" for VS2013.
  4. The installation includes an install of the newer SysCAD Reaction Editor version 1.2.

SysCAD 9.3 License

  1. SysCAD 9.3 Build 136 uses Crypkey Version 8 and includes updated SysCAD License Utility version 3.0.
  2. Separate copies of the latest version of SysCAD 9.2 Build 135 are available using Crypkey 7 and Crypkey 8.
  3. We recommended changing to using latest SysCAD 9.2 Build 135 with Crypkey8 so that all SysCAD use is with Crypkey8.
  4. If using a stand-alone USB Key it is possible to use older versions of SysCAD 9.2 and SysCAD 9.3.
  5. If SysCAD 9.3 does not recognise the USB Key, the Key may need updating. Please contact us so that we can send an update file.
  6. If using a software license, it is not possible to use older versions of SysCAD 9.2 and SysCAD 9.3. The latest version of SysCAD 9.2 Build 135 using Crypkey 8 can be used. The Build 135 update files using Crypkey 8 will include "_ck8" in zip filename.
  7. To upgrade an existing software license folder, the versions of syscad.exe and crp32002.ngn shipped with SysCAD 9.3 need to be copied to the license folder. Once upgraded older versions can no longer use the license.
  8. For network licenses, there is a new version of ELM. The network license includes a new TCPIP option.
  9. Refer to Crypkey Version 8 for further details.

Recommended Project Upgrade Procedure

Step 1 - Use a converged model

Check that the project in SysCAD 9.2 is saved converged and is working correctly. This will make it much easier for testing and comparing results in upgraded 9.3 project. It is also recommended that you upgrade the project to the latest Build 135 before upgrading to SysCAD 9.3. Projects upgraded from Build 134 and earlier do not necessarily upgrade as smoothly as recent Build 135 projects.

Step 2 - Backup

Create a backup of your entire project folder, including the CfgFiles folder. (This is VERY important, as you may wish to return to using 9.2, to compare results and configuration with the upgraded project in SysCAD 9.3.)

Step 3 - Edit Configuration File

Start SysCAD 9.3 and go to Edit Project Configuration and edit the project configuration file. The configuration file will automatically be upgraded as well as the associated species database.
The configuration file in SysCAD 9.3 has a number of new features. (Please see Project Configuration (cfg File) for a full description of all of these new features). Changes and improvements include:
  • In Step 1 of 2, re-organised unit models within model libraries (DLL files) and changed the name (ie UnitType) of many of the models.
  • New option on Species tab for sorting of species as custom by phase. You may want to change from Custom to Liq-Sol-Gas Custom or similar.
  • Naming of species tags and calculation tags is stricter (additional special characters not allowed). You may need to come back and change these tags.
  • Stricter testing of when volume views are allowed for custom calculations, eg. not allowed for aqueous species with density correction functions. This will prevent the project from loading.
  • Complete rework of managing species used in a project, including options to use "hardwired" SysCAD properties for some species. New tab pages for each phase to give summary of properties used for each species.
  • Configuration of Particle Size Data (PSD) has been simplified by combining Distribution and Sieve Series definitions.

Step 4 - Resolve Database Issues

The species database will be automatically upgraded from MS Access mdb file to SQLite db3 file. Resolve all species database issues, if there are any by editing the species database. :There are 3 ways you can do this:
  1. From within the Configuration Editor at Step 2 of 2, double click on a species or click on the Edit User Database button.
  2. In the 'Project Configuration' dialog box click on the Edit Species DB button.
  3. Go to 'Species | Edit User Database...' menu option, then browse for the required species database and then select the associated cfg file.
During species database upgrade SysCAD generally automatically upgrades the data, fixes formatting and gives messages about the changes made.
(Please see Editing User Species Database 9.3 for details on the new layout and fields.)

Tip: The upgrade will usually be smoother if you make as many of the required changes in SysCAD 9.2 prior to upgrading. This may mean doing a test upgrade to identify the issues, then going back to the original project in 9.2 to make the changes, and then doing the upgrade proper.

Possible Database Upgrade Issues

  1. Database can't upgrade if density specified as constant and density correction function. Upgrade from 135 is halted if for any aqueous species with a density correction function, a constant density is also specified. Note that this does not display in the edit database dialog (which is greyed out). It is in the underlying Access database. The solution is to manually remove the constant densities from species database in MS Access prior to the upgrade step.
  2. Unrecognised equations for properties of species. If this occurs you will need to edit the problem species and check the the equation for the problem property.
  3. Stricter naming of species tags may require renaming of some species compound names. '+' and '-' characters can now only occur at the end of the compound name. SysCAD 9.3 has stricter testing of allowed characters, so you may need to delete or change illegal characters. Please see SysCAD Tags for more details. It may be easier to make the changes in SysCAD 9.2, prior to upgrading.
  4. SysCAD 9.3 will not allow a non-zero H25 for Standard Species. If this was the case in the 9.2 project, H25 is forced to zero which may affect results in your project.

Step 5 - Open Project (Part a)

Open the project. Do not save the project.
Review the warnings and error messages. Many of the messages will be related to the project upgrade, so you may need to scroll past these to look for errors and warnings related to the project load.
BEFORE saving the projects you will want to resolve any errors related to loading referenced files.
The first important error to look out for is any PGM or MP files that fail to load. The errors in the PGM code that prevent a PGM load must be resolved first. If the project is saved without correcting these then the state (values) of the pgm variables may be lost. The best approach is to resolve PGM load errors, exit SysCAD without saving the project, then reload the project.
There may be other errors loading reaction files or the species database that can be resolved at this time.
During this step you are fixing any errors in external files. You are not changing or fixing anything in the project yet so you do not need to save the project. Close the project and reload as often as may be required.

Step 5 - Open Project (Part b)

Open the project again, if the project is free of any errors and warning related to project loading, then carry out a Save Project As command and select a new project name.
Continue reviewing warnings and errors, making the required corrections. Many of the potential issues are described in the sections below (see Project Upgrade Notes - Resolving any Issues). Save and reload the project as often as may be required.

Step 6 - Solve the Project (Part a)

Once (a) the configuration file, species database & project have been upgraded; (b) the project saved to a new name; and (c) all important load errors and warnings have been resolved and/or reviewed, then you are ready to resolve any potential errors that may occur when you solve the upgraded project.
There may be warnings and error messages when solving a newly upgraded project. These may be related to tag name changes, discontinued tags, rearranged options or other changes in SysCAD 9.3. Many of these common issues are described in the Resolving any Issues.
Rather than solve the project, select the menu option Actions|Idle as this performs the solver startup tests before solving any iterations. Then you can resolve any solver startup issues before looking at any issues that occur while solving. If there are errors, stop the solver then make corrections, select Idle again and repeat.
Once the project has solved for at least one step, SysCAD would have generated a list of old tags that needs changing in any reference files such as PGM / MP. It is recommended that these old tags be changed at this point, please follow instructions listed in document Managing Tag Changes to change any old tags.

Step 6 - Solve the Project (Part b)

Now that any solver startup issues have been resolved, you are ready to solve the project, again reviewing the errors as they occur during the solver iterations.
Once any issues have been resolved, the project results can be compared to previous results to determine if there are any significant differences that need investigation. Some small differences in results as described in Changes that may affect results below.
Remember to also check the Excel inputs and reports to check that these still work as expected and don't have any messages about invalid tags, please follow instructions listed in document Managing Tag Changes to change any old tags in Excel files.

Step 7 - Other Projects

For all other projects which use the same species database and configuration file, repeat step 4 and 5 only. The configuration file and related species database only needs to be upgraded once for all the projects that reference this.

Project Upgrade Notes - Resolving any Issues

The following sections describe changes that may effect the project upgrade process. The details of changes that may affect the project upgrade are described. Changes that may need to be made manually corrected are also described.

Species Database

The species database has been altered substantially from previous SysCAD versions. (Please see Editing User Species Database 9.3 for details on the new layout and fields.) The species database name has also been changed from SysCAD.92.mdb to SysCAD.93.d3b and is now saved as an SQLite database. Generally, the upgrade process will automatically convert an existing 9.2 database into the new format required for 9.3.
There are a number of methods for upgrading the database:
  1. Start SysCAD 9.3 and go to Edit Project Configuration and edit the required configuration file.
  2. Start SysCAD 9.3 and open an existing SysCAD 9.2 project.
  3. Start SysCAD 9.3 and select 'Species | Edit User Database...' menu option, then browse for the required species database and select the associated cfg file.
In all of the above cases:
  • SysCAD will automatically attempt to upgrade the species database to the 9.3 format.
  • If there are no issues with any of the species (there are more rigorous checks in place in 9.3) you can continue and you may view any upgrade messages in the Message window.
  • If there are some issues with any of the species then you will need to resolve these. SysCAD will display error messages in the Message window.
  • You may then open the species database and correct any issues and you may need to open the configuration file as well and correct any issues with the species list.

Configuration (cfg) File

  1. There may be problems with Custom Species Calculations when upgrading to SysCAD 9.3 as the checks on the settings are more rigorous. The user may need to make the following changes in the Configuration File (For more information see Species Calculations Views):
    • Change the View to a simpler setting - e.g. from 'Mass, Volume, Molar' to 'Mass, Molar'; and/or
    • Simplify the Basis setting - e.g. from 'All, Phase, IndPhase' to 'All, Phase'

Global Settings

Some of the defaults for Global settings are different and there are new options. These may not match your preferences, or what you are used to in SysCAD 9.2. You can review these settings in General Options 9.3.
The most important of these is a new option for how editing of a field in the Access window or Trend page works. There is a new option called "Excel Style Field Editing" in General Options More. To use the SysCAD 9.2 style of editing fields untick this option.

Tag Changes

There are a significant improvements related tags. IMPORTANT: Review SysCAD 9.3 Tag Changes for a detailed description of tag changes, resolving issues and new options for upgrading old tags. A few key points:

PGM Changes

  1. Any PGM (or MP) file load errors should be resolved first when opening a project. Saving the project before fixing load errors will result in a loss of PGM and MP variable values.
  2. Stricter Testing of Species Database Class (SDB) functions that now only work for a species with a specific phase. eg. SpVapourP will only work if the specified species is a vapour species. The function SDB.FindSpecie() has been renamed to SDB.FindSpecies().
  3. If old tag names are used in the pgm they should be upgraded to use new tag names otherwise referenced tag indicators are not shown. Messages are given during solver startup or while running when old tags are used. For details, see Managing Tag Changes.
  4. By default, projects upgraded from SysCAD 9.2 will have the Old135Format tick box selected. This ensures the PGM file execution will be the same as SysCAD 9.2 and allows the use of Oninitialise() and OnTerminate() to function as before. However, if user wants to change the PGM file to make use of the new Trigger Subroutines in SysCAD 9.3, then all Oninitialise() and OnTerminate() codes will have to be change to the new trigger subroutine format.
    Please see PGM Execution SysCAD 9.2 vs SysCAD 9.3 for more information.
  5. The OnStart special variable is no longer recognised in a PGM.
If still required, workaround is:
; define own parameter
Bit On_Start
; set parameter to TRUE during initialisation
if (OnInitialise)
   On_Start = TRUE
; use new parameter and set to false
   On_Start = FALSE

Change in numbering of multiple internal models to start from 1 rather than 0

Some control models such as PID Controller, Set Tag Controller, Noise Controller, Profile Controller, General Statistics, Flow Statistics, Scheduled Events and Downtime that have multiple models within them are now numbered starting at 1 rather than 0. The numbering is not automatically changed with project upgrade. These models do have a button that changes them to use the new numbering.
IMPORTANT: When updating the numbering if there are any external files (eg PGMs, PIDs, Excel reports, etc) referencing the tags, then the user needs to manually fix these. The fix usually involves changing the indexing in the full referenced tag by +1.
NOTE: These models need the numbering to be updated before Copy & Paste of these models will work correctly.

Other Changes

  1. Excel TagSelect reports referencing model Unit Types (called ClassId in 9.2 but now called UnitType) will need updating because of changes to model unit names. For example, "Feed_XPG" is now "FeederSink" and "MakeupSrc" is now "MakeupSource".
  2. The COM Automation files have been changed. They have different names. If you have VBA Macros that call SysCAD you will need to change the references in VBA to "SysCAD 9.3 Application Library" and "SysCAD 9.3 Solver Library" (SysCAD93.tlb and ScdSlv93.dll). The application type has been changed from "SysCAD.ScdApplication" to "SysCAD93.ScdApplication". The Program ID has changed from "SysCADSimulator.Application" to "SysCADSimulator93.Application".
  3. The SysCAD 9.3 OPC Server name is unchanged, it is still "SysCAD.OPC.1". For a dynamic project using OPC, when changing between SysCAD 9.2 and 9.3 you will need to run regall as administrator to update registry between sessions.
  4. For the Noise Controller (dynamic projects), the "On" tag has changed to "Action". Due to new list of available options, old tag (deliberately) does not map to new tag. User needs to decide what changes in logic they want to make. Also, can no longer have different frequency for each noise block. New option to set frequency for a whole noise model so if want noise blocks with different frequencies then will need to use separate noise models. You can't solve the model until confirming that the settings are OK.
  5. Alumina1 DLL with Generic Bayer Species Model and Precipitation Model are no longer included with standard SysCAD 9.3 install. These models are no longer supported and projects should be converted to use Alumina3. A SysCAD 9.3 version of Alumina1 is available on request for project conversion purposes.

Changes that may affect results

The following list gives changes that may effect the results of a project. Other than the changes listed below it is expected that a steady state model should converge (within usual tolerance) to the same result as the SysCAD 9.2 converged project.
  1. H25 for Standard Species
    In SysCAD 9.2 it was possible to use a non-zero H25 value for Standard Species. This is now forced to zero. If this was non-zero then results may be affected.
  2. Activate/Deactivate Flowsheet Tags have changed in SysCAD 9.3, users using these tags to activate/deactivate flowsheets via external packages (such as MS Excel) should review and update the files before running the macros. Plant Model - Flowsheets Tab
  3. Noise controller execution frequency has been changed to common frequency per Unit model. Noise controller requiring a different executing count need to be moved to a new controller.
  4. Calculations for thermal conductivity (VThermalCond, LThermalCond) of pure steam and pure water have been improved. This also affects the calculation of the PrandtlNo (VPrandtlNo, LPrandtlNo).
  5. In a Dynamic Tank, the "SpeciesFilter" Filter.Method (on the Connect tab page) does not upgrade, as the possible selections with this option have changed. If this method was used, you will need to reselect this method and make the appropriate selections.
  6. For Alumina projects using Precipitation tanks, the bound soda calculation methods has changed. The Original method is no longer available, user should change to the Ohkawa bound soda method. Please change the method and re-tune the constants K_tuneBS and K1 as these may be different to 9.2.
  7. In Dynamic projects, the maximum number of iterations per timestep (MaxIterations) will be reset to the default of 20 once a project is upgraded to SysCAD 9.3. The user can change this on the Solver Settings - Convergence page.