Importing PSCAD V4 Projects to X4

Importing a V4 project (v4.2.1 only!) into PSCAD X4 is for the most part, as simple as a couple of mouse clicks. Simply select the PSCAD tab in the ribbon control bar and select Open | Import Project, to import a v4.2.1 project.

Upon import, PSCAD will create a new file and convert your original project to the new file format. Your original project will be left untouched. Project files are converted as follows:

As mentioned above, it is not possible to save back to the older format, so any changes made to the new project files cannot be migrated back. If you need to maintain files in both formats, then you must make equivalent changes in the old format and the new separately.

If all goes well, the above procedure is all that is needed to upgrade your PSCAD V4 projects to X4. During the import process however, there may have been compatibility issues in migrating your project over to the new format. These issues may not arise until you attempt to compile and run the new project.

The following sections attempt to describe most of the issues that you may experience with a newly imported project, as well as other important topics you should be aware of.

Duplicate Definition Linking Priority

Every project, be it a case or a library, contains component or module instances. The definitions, on which these instances are based, may or may not be stored in the project. They may in fact be stored in previously loaded, user library projects, the master library, or a combination of both. There may be situations where duplicate definitions exist in the workspace (i.e. definition sharing the exact same name).

So, how do we choose a definition if there are duplicates? To avoid chaos on import, there must be certain rules imposed. In previous versions of PSCAD, the definition linking mechanism was given a set of priorities: Any definition residing in the master library was given first priority; then previously loaded user-defined library projects (i.e. *.psl files); then the local project itself. For example, say a user has a custom definition called resistor, which is stored in a case project. When the case is loaded into the workspace, PSCAD v4.2.1 would link any instances of the resistor in the case project to the master library definition of the same name, not the local resistor definition.

A fundamental change was made in PSCAD X4 effectively reversing the older priority set. Now the local definition is given priority, then user library definitions, then the master library, upon load or import of a project.

Namespace Linking

Note that the above linking priority is imposed only when projects are first imported. This is because component instances were linked to their definition by name only; no information was given on where the definition resides. As such, PSCAD needed to rely on the linking priority in order to 'best guess' which definition to link to.

A new concept called Namespace Linking was introduced in PSCAD X4, which provides project information (or scope) to each definition. Once your project has been saved in X4 format, all definition links will possess both a definition name and an namespace name. In this manner, PSCAD no longer needs to guess where the definition is: If the corresponding project is not loaded, then the component looking for a definition in that project simply appears as a placard.

With the namespace concept comes a variety of other convenient features that allow users to link and re-link their components from one definition to another. See Definition Referencing for more details on this.

Problems to be Aware of

If you have duplicate definitions in your workspace, you may experience problems when compiling imported project files. These problems may manifest themselves in many ways, but the most common problem arises when your project contains a local definition (or many) that shares the same name as a definition residing externally in either a user library project, or the master library.

A user possesses a case project that contains an unused definition (i.e. it does not have any instances) called integral.

In PSCAD v4.2.1, this definition would always be ignored, as this is also the name of a master library definition, and the linking priority was master library first; so the master library integral definition would always be linked to the instances in the case. If this case project is imported into PSCAD X4 however, the local integral definition will by default be linked to all instances of integral in your project.

This will most likely result in compilation errors and other problems. Or, it may even go undetected!

These problems are best dealt with before a project is imported into PSCAD X4. The following is a checklist of tasks that should be performed in PSCAD v4.2.1 prior to importing your project:

Illegal Character Issues

There is an assortment of characters that are not allowed as part of any XML content, as they are used by the language as delimiting characters. These characters were initially deprecated in PSCAD v4.0 (2003), but have been functioning in ‘compatibility mode’ until now. In previous versions, editing a component definition with input parameter Symbol names containing any of these characters would result in a similar dialog to the following:

Upon import of existing projects into X4 (i.e. *.psc and *.psl files), these characters will be replaced automatically (when used in certain situations), as their presence is detrimental to the structure of the project file under the new XML standard.

The following is a list of areas where these characters will be replaced if found by the importer:

Modification of Script

Modification of component script has been provided as an adjustable application option.

A PSCAD v4.2 project is to be imported into X4, and contains a user-defined component definition. The definition contains a parameter with Symbol name Xd’’. Upon import of the project file, the X4 importer detects the illegal characters in the Xd’’ parameter and replaces them with underscore characters (as described above). As a result, the parameter Symbol name will be Xd__ following import of the project file.

The importer does not however, modify the component definition script sections. As a result, if this parameter Symbol name is used in any substitutions in the script, compile errors will occur. The Checks section of this component is defined as follows:

ERROR The quantity Xs cannot be greater than Xd : (Xs<Xd'')

Since the Xd’’ symbol name was not replaced, if left as is PSCAD will issue a build error message similar to the following upon compile of the project:

Checks Script Error: Evaluate: (Xs<Xd'')[Error]; Evaluate: 'Xd''' is not a parameter, computation or constant.

The user must therefore modify the script section (in this case the Checks segment) as follows:

ERROR The quantity Xs cannot be greater than Xd : (Xs<Xd__)

Helpful Legacy Import Tools

There are a few convenient tools available to you when importing or loading your legacy (older) projects:

All of these tools are application options. See Recovery & Import for a description of each.

Adding Multiple Instance Module Support to User-Defined Components

With the inclusion of Multiple Instance Modules (or MIM) in PSCAD X4, changes to EMTDC system dynamics functionality were unavoidable. This means that some user-defined components may need to be modified to support their usage within a module with multiple instances. Components that support usage within multiple instance modules are referred to as Runtime Configurable.

Other New Features

For a complete list of all that is new in PSCAD X4, please see the What’s New? topic in the online help (In the online help, go to Opening Screen and click the What’s New? link).

Old File Format	New File Format
<project_name>.psc	<project_name>.pscx
<project_name>.psl	<project_name>.pslx

In v4.2.1	New in X4
Master Library	Local Project
Other Library Projects	Master Library
Local Project	Other Library Projects

Old Definition Name Format	New Definition Name Format
<definition>	<namespace:definition>

Character	Name	Replaced By
&	Ampersand	_
< >	Inequality Signs	_
"	Quotation Mark	_
'	Apostrophe	_
°	Degree	deg