UCM | Iteration

Background

Non-linear elements require iterative-based solvers within a time step to enable more accurate results. HYPERSIM has an iterative method (see Simulation Settings to activate this option if necessary) for its non-linear elements.

However, prior to v. 2020.1, UCM-type components could not benefit from this iteration method. UCM-type components are now able to use the iteration method presented in HYPERSIM.

Changes To UCM Model Definition File

In comparison to the pre-existing UCM code structure, new parameters and sections were added to the UCM model definition template file. This enables UCM models to iterate within a time step during the simulation.

• A new field in the General Information section is added in order to indicate whether or not the UCM supports the iteration.
• A new parameter called UCM_Iteration is added to enable or disable iterations.
• Two new sections (section 9.5i - Before “nodes voltage calculation” iteration function code and section 9.6i - After “nodes voltage calculation” iteration function) are added in order to allow the UCM to define all the actions and operations required at the start of the step and all the calculations and operations required for each iteration.

UCM Iteration Options and Settings

General Information or Parameters (Section I-1)

The parameter UCM_ITERATION specifies if the UCM supports iteration as shown in Figure 1.

The two possible values for this attribute are:

The fragment of code below shows an example of the new parameter UCM_ITERATION in the General Information or Parameters section of the UCM model definition template file for a non-linear resistance.

%% I- Model description.
%%
%%   1- General informations or parameters.
%%      -----------------------------------
%%
%%      UCM_NAME:          Model Unique Name, already assigned
%%      UCM_TYPE:          Model type (Choice of NetworkElement or CommandBlock)
%%                         Default: NetworkElement.
%%      UCM_CATEGORY:      Model category (Breaker, Transformer, etc.)
%%                         Default : User
%%      UCM_VERSION:       User's model version number (in a string)
%%      UCM_EXEC_TIME:     Estimated model's average simulation step time.
%%                         Default: 5.0e-6 s.
%%      UCM_DESCRIPTION:   Short description of model (one phrase).
%%
%%      Optionals:
%%      ----------
%%
%%      UCM_LOADFLOW_TYPE: Load-flow model type (Admittance or Generation).
%%                         Default: Model NOT considered for load-flow.
%%      UCM_ITERATION:     Specify if the model supports iteration (Yes or No).
%%
%%
%%vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
%% BEGIN GENERAL INFORMATION -- Enter or modify general information

UCM_NAME          = LnonLin 
UCM_TYPE          = NetworkElement
UCM_CATEGORY      = User
UCM_VERSION       = "1.0"
UCM_EXEC_TIME     = 5.0e-6
UCM_DESCRIPTION   = "A 3-phase Yg non-linear inductor"
UCM_LOADFLOW_TYPE = Admittance
UCM_ITERATION     = Yes

%% END GENERAL INFORMATION

Automatic Generation of Iteration Tab in UCM Model Form

When the UCM model is compiled, it automatically generates a Iteration tab in the UCM model form and the variable Enable Iteration can be set (0 or 1) in this tab.

Figure 1 shows the Iteration tab of an UCM model exemple  of a non-linear resistance.

Figure 1. Iteration tab in UCM form when UCM_ITERATION field is added in the General Information section for an UCM model exemple of a non-linear resistance

In order to ensure compatibility of UCM models developed in previous versions of HYPERSIM, the UCM_ITERATION parameter is set to optional by keeping the default value to No. In the same way, UCM models open in version 2020.1 but made in previous versions can benefit from this new feature by adding the UCM_ITERATION variable and set it to Yes and adding new sections 9.5i and 9.6i.  

When the UCM iteration option is selected by the user, the number of iterations can be defined by enabling the option Activate iterative method and specifying the maximum number of iterations in the Simulation Settings of HYPERSIM.

It should be noted that in HYPERSIM, when activating iterative method it automatically selects the Apply to all nonlinear elements option by default, so even if the UCM iteration option is not selected by the user, the UCM model would iterate.

Figure 2 shows the interface elements that warn the user to verify the iterative method option when working with the UCM iteration option.

Figure 2. Precaution when activating the iterative method option when working with the UCM iteration option

Before "nodes voltage calculation" function code (Section 9.5)

This section includes all the actions and operations required at the beginning of the step, which are used to prepare the simulation and are validated for each iteration. This code section is only executed once per time step, for example when processing the input signals.

It is important not to change the results obtained in the following sections: preVNodeIter,  postVNodeIter  and  postVNode, as they will not be re-calculated in subsequent iterations.

Before "nodes voltage calculation" iteration function code (Section 9.5i)

New section added to support iteration. In this section, all the calculations and operations required to adjust the simulation to a current segment or state of te UCM within an iteration are executed. This section is executed for each iteration in order to adapt the admittance matrix and / or the current injection. 

The fragment of code below shows the section 9.5i for a non-linear resistance when the UCM iteration is implemented.

%%^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
%%
%%     9.5i-  Before "nodes voltage calculation" iteration function code.
%%            Code executed before "nodes voltages calculations" when iteration 
%%            is enable.
%%
%%vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
%% BEGIN BEFORE VOLTAGE CALCULATION ITERATION CODE

int     i;    // Compteur

/* Initialize indication of nodes affected by changing in segment */

for (i = 0; i < 3; i++)
{
	ucmNodeChanged(i) = 0;	
}

/* In the segment has changed, determine the additional conductance and indicate that the 
   corresponding nodes are affected                                                       */

/* Phase A */

if(Seg_ChFlag[0]) 
{
	ucmYadd(T_a,T_a)    = Gadd_vect[Seg[0]];
	ucmNodeChanged(T_a) = 1;
}

/* Phase B */

if(Seg_ChFlag[1]) 
{
	ucmYadd(T_b,T_b)    = Gadd_vect[Seg[1]];
	ucmNodeChanged(T_b) = 1;
}

if(Seg_ChFlag[2]) 
{
	ucmYadd(T_c,T_c)    = Gadd_vect[Seg[2]];
	ucmNodeChanged(T_c) = 1;
}

/* Calculating historical current sources ( I = G*V + I0 ==> I = G*V + B) */ 

Ihist_a = B_vect[Seg[0]];
Ihist_b = B_vect[Seg[1]];
Ihist_c = B_vect[Seg[2]];


%% END BEFORE VOLTAGE CALCULATION ITERATION CODE

After "nodes voltage calculation" function code (Section 9.6)

This section includes the calculation of all output signals and historical values. It is only executed after the iterative process is completed. The calculations for preparing the next step are also executed in this section.

After "nodes voltage calculation" iteration function code (Section 9.6i)

A new section has been added to support iteration. All the calculations and operations required to determine if the additional iteration is required are executed in this section.

The calculations presented in this section are made at the end of each iteration. It is important not to modify the historical values in this section.

The function must return 1 if the user selects the UCM model to iterate and returns 0 otherwise. The fragment of code below shows the section 9.6i for a non-linear resistance when UCM iteration is implemented.

%%^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
%%
%%     9.6i-  After "nodes voltage calculation" iteration function code.
%%            Code executed before "nodes voltages calculations" when iteration 
%%            is enable.
%%
%%            Returns an integer that indicates if we need to iterate:
%%            return 0 -> no need to iterate,  return 1 -> need to iterate
%%
%%vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
%% BEGIN AFTER VOLTAGE CALCULATION ITERATION CODE

int    Seg_act[3];
int    i;
double Phi_a, Phi_b, Phi_c;

/* Establishing actual segment per phase */ 

for (i = 0; i < 3; i++)
{
	Seg_act[i] = Seg[i];	
}

/* Scanning saturation flux in order to change segment */ 

/* Phase A */

/* Translating from Voltage to Saturation Flux --> Flux = Flux + T/2*(Vkm(k) + Vkm(k-1)) */

Phi_a = Phi_hist[0] + ( ( ucmTimeStep / 2 ) * ( ucmVNode(T_a) + Vnode_hist[0] ) ) ;

if ( (Phi_a) > vecPhi[Seg[0]+1] ) 
{
	while ( (Phi_a) > vecPhi[Seg[0]+1]) 
	{
		if ( Seg[0] >= 2 * nB_Data )
			break;
		
		Seg[0]++;
	}
}
else if ( (Phi_a) < vecPhi[Seg[0]] ) 
{ 
	while ( (Phi_a) < vecPhi[Seg[0]] ) 
	{		
		if ( Seg[0] <= 0 )
			break;
		
		Seg[0]--;
	}
}

/* Phase B */

/* Translating from Voltage to Saturation Flux --> Flux = Flux + T/2*(Vkm(k) + Vkm(k-1)) */

Phi_b = Phi_hist[1] + ( ( ucmTimeStep / 2 ) * ( ucmVNode(T_b) + Vnode_hist[1] ) ) ;

if ( (Phi_b) > vecPhi[Seg[1]+1] ) 
{
	while ( (Phi_b) > vecPhi[Seg[1]+1]) 
	{
		if ( Seg[1] >= 2 * nB_Data )
			break;
		
		Seg[1]++;
	}
}
else if ( (Phi_b) < vecPhi[Seg[1]] ) 
{ 
	while ( (Phi_b) < vecPhi[Seg[1]] ) 
	{		
		if ( Seg[1] <= 0 )
			break;
		
		Seg[1]--;
	}
}

/* Phase C */

/* Translating from Voltage to Saturation Flux --> Flux = Flux + T/2*(Vkm(k) + Vkm(k-1)) */

Phi_c = Phi_hist[2] + ( ( ucmTimeStep / 2 ) * ( ucmVNode(T_c) + Vnode_hist[2] ) ) ;

if ( (Phi_c) > vecPhi[Seg[2]+1] ) 
{
	while ( (Phi_c) > vecPhi[Seg[2]+1]) 
	{
		if ( Seg[2] >= 2 * nB_Data )
			break;
		
		Seg[2]++;
	}
}
else if ( (Phi_c) < vecPhi[Seg[2]] ) 
{ 
	while ( (Phi_c) < vecPhi[Seg[2]] ) 
	{		
		if ( Seg[2] <= 0 )
			break;
		
		Seg[2]--;
	}
}

/* Loading Vnode_hist vector */ 

Vnode_hist[0] = ucmVNode(T_a);
Vnode_hist[1] = ucmVNode(T_b);
Vnode_hist[2] = ucmVNode(T_c);

/* Loading Vnode_hist vector */ 

Phi_hist[0]   = Phi_a;
Phi_hist[1]   = Phi_b;
Phi_hist[2]   = Phi_c;

/* if Seg_ChFlag != then an iteration must be performed */ 

Seg_ChFlag[0] = Seg[0] - Seg_act[0];
Seg_ChFlag[1] = Seg[1] - Seg_act[1];
Seg_ChFlag[2] = Seg[2] - Seg_act[2];

return (Seg_ChFlag[0] != 0) || (Seg_ChFlag[1] != 0) || (Seg_ChFlag[2] != 0);

%% END AFTER VOLTAGE CALCULATION ITERATION CODE

Impact of New Sections on the Code Generated

The way HYPERSIM invokes the functions of a UCM supporting the iteration and how this is reflected in the code generated is different if the iteration is activated or not for a given instance of the UCM model.

The example code below illustrates how HYPERSIM invokes the iteration functions of a UCM with the iteration option enabled or disabled.

In this fragment of code, the iteration option is disabled so that the resulting code generated shows that HYPERSIM invokes the UCM iteration functions (ucm_MyModel_preVNode, ucm_MyModel_preVNodeIter, ucm_MyModel_postVNodeIter and ucm_MyModel_postVNode) outside the iteration loop.

Task_sim()
{	
	ucm_MyModel_preVNode();
    ucm_MyModel_preVNodeIter();

BeginIteration:
	
	/* ... */
		
YVI:

	/* solutionner vnode */
	/* ... */
	
	if(iterFlag)
	{
		iterFlag = 0;
		goto BeginIteration;
	}

	ucm_MyModel_postVNode();
	ucm_MyModel_postVNodeIter()
}

In this fragment of code, the iteration option is enabled so that the resulting code generated shows that HYPERSIM invokes the UCM iteration functions (ucm_MyModel_preVNode, ucm_MyModel_preVNodeIter, ucm_MyModel_postVNodeIter and ucm_MyModel_postVNode) inside the iteration loop.

Task_sim()
{	
	/* initialisation des historiques de contribution des sources aux Inode */
	SigFSav[2] = 0;
	/* ... */
	ucm_MyModel_preVNode();

BeginIteration:
	
	ucm_MyModel_preVNodeIter();
	
	/* UCM: contribution des sources aux Inode */
	SigF[1] += (SigF[2] - SigFSav[2]);
	SigFSav[2] = SigF[2];
	/* ... */
	
	/* UCM: affectation de nodeModifiedMin */
	/* ... */
		
YVI:

	/* solutionner vnode */
	/* ... */
	
	iterFlag |= ucm_MyModel_postVNodeIter();
	
	if(iterFlag)
	{
		iterFlag = 0;
		goto BeginIteration;
	}

	ucm_MyModel_postVNode();
}

Simple Example of a UCM Model of Non-linear Resistance

In this simple example, a UCM is created to model a three-phase non-linear R circuit and compare it with a non-linear R native component. Figure 3 shows a simple example implemented to demonstrate the UCM iteration feature.

Figure 3. A simple example to demonstrate the UCM iteration feature.

Non-linear resistance voltage and current parameters of the UCM are shown in Figure 4.

Figure 4. V-I characteristics of the non-linear resistance for both components (UCM non-linear R model and HYPERSIM native non-linear R model).

Figure 5 and 6 show the bus voltage and current waveforms of the UCM model of non-linear resistance and the HYPERSIM native model of non-linear resistance. In Figure 5, the UCM model has the iteration option disabled while the HYPERSIM native model has the iteration option enabled. The difference between both waveforms is best seen when there is a changment in a V-I segment, causing inaccuracy in the resulting resistance value when the UCM model does not take part of the iteration loop.

Figure 5. Voltage and current waveforms comparison when the UCM model of non-linear resistance does not participate in the iteration loop.

Finally, in Figure 6, the UCM model has the iteration option enabled as the HYPERSIM native model. It can be seen that there is no difference between both waveforms as there is no inaccuracy when changing in a V-I segment is reached.

Figure 5. Voltage and current waveforms comparison when the UCM model of non-linear resistance does participate in the iteration loop.