3.12.3 CancelTerms

Command structure of CancelTerms.

CancelTerms simplifies the given DAEObject by successive removal of terms in the equation system. It assures that the behavior of the simplified system differs not more than maxerrors from the behavior of the original system. Before using CancelTerms, the DAEObject has to be prepared for nonlinear simplification using NonlinearSetup. CancelTerms performs the numerical analyses set by the call to NonlinearSetup to calculate the error a simplification causes. The error list maxerrors must contain an error bound value for each analysis mode and each output variable, i.e. it has to be a list of the form

-> -> , ,

Variables for which an error value has been specified in the call to NonlinearSetup can be omitted. If error specifications have been given for each analysis mode and each output variable in the call to NonlinearSetup, the maxerrors specification can be omitted completely. If the error caused by a simplification exceeds any of the maximum errors given in the error list, the simplification is undone. Note that the error is measured by the error function specified in the call to NonlinearSetup.

Removal of terms is done in the level given by the option Level (see below).

CancelTerms returns the simplified DAEObject. All settings for nonlinear simplifications stored in the original system are added to the returned DAEObject, too. This means that you do not have to call NonlinearSetup again on the new system in order to apply subsequent simplifications.

Note that CancelTerms reduces the number of terms only. Use CompressNonlinearEquations to reduce the number of equations.

CancelTerms provides the following options:

Options for CancelTerms.

After removal of one or more terms a numerical simulation is performed. Comparing the result to a reference calculation yields the error on the output variables.

See also: NonlinearSetup, ShowCancellations, ShowLevel, Statistics.

Options Description

A detailed description of all CancelTerms options is given below in alphabetical order:

Clusterbound

Usually, CancelTerms deletes several terms at once before performing a numerical error calculation. The computation of suitable term clusters for this is done automatically by CancelTerms. If the precasted influence of a term exceeds a given threshold, calculation of clusters is stopped and cancellation is done term by term. This threshold value is specified by the option Clusterbound. The following values are allowed:

Values for the Clusterbound option.

The default setting is Clusterbound -> -1. Note that deletion of terms using clusters speeds up the computation significantly.

Errorbound

If the computed error exceeds the given error bound maxerrors, then the term or terms are re-inserted. The option Errorbound specifies the number of successive re-insertions before the algorithm terminates. Use Errorbound -> Infinity to check all terms for cancellation. The default setting is Errorbound -> 3.

Level

By default, CancelTerms removes terms from top-level sums (level 0). It is also possible to simplify sums in deeper levels, i.e. sums occuring inside of expressions. The option Level determines which level is affected by the simplification. Possible values are:

Level specifications for CancelTerms.

If given explicitly, level specifications have to be non-negative integers. The default setting is Level -> 0.

Ranking

Cancellation of terms is performed in a pre-calculated order which sorts the terms by increasing influence. A method which estimates the influence of a cancellation on the output behavior is called ranking. CancelTerms lets you choose which ranking method to use for each analysis mode separately by means of the Ranking option. Possible values are:

Values for the Ranking option.

The ranking method can either be Automatic, which means to use the internal implemented ranking function, or Simulation, which means to use the corresponding simulation function to calculate the influence. The former is much more efficient while the latter is more accurate. If the option value is the symbol Automatic or Simulation the corresponding ranking function is set for all analysis modes simultaneously. If you want to set the ranking function for each mode separately, you have to give a list of rules. The current analysis mode is then matched against the left hand side of the rules and the corresponding right hand sides are chosen as ranking functions. Thus, mode can either be one of the symbols DT or AC, or a pattern specification like _. The default setting is Ranking -> Automatic.

RecordCancellations

The value of the RecordCancellations option determines whether term cancellations are recorded during computation. If set to True, a cancellation history is written to the options section of the DAEObject given as argument to CancelTerms. Note that it is not written to the returned DAEObject. The command ShowCancellations can then be used to visualize the history list. If set to False, no history list is recorded. The default setting is RecordCancellations -> True.

Examples

Load Analog Insydes.

In[1]:= <<AnalogInsydes`

Read PSpice netlist.

In[2]:= netlist = ReadNetlist[
"AnalogInsydes/DemoFiles/Sqrt.cir",
Simulator -> "PSpice"]

Out[2]=

Set up symbolic circuit equations.

In[3]:= mnaFull = CircuitEquations[netlist,
AnalysisMode -> DC, ElementValues -> Symbolic,
Value -> {"*" -> {TEMP, TNOM, $q, $k}}]

Out[3]=

Prepare DAE system for nonlinear simplifications.

In[4]:= step1 = NonlinearSetup[mnaFull, {II, VLOAD}, {I$VLOAD},
DT -> {Range ->
{{VLOAD, 0., 3.5, 0.5}, {II, 0., 0.001, 0.0002}} }]

Out[4]=

Display complexity information of the original system.

In[5]:= Statistics[step1]

Cancel top-level terms in the equations.

In[6]:= step2 = CancelTerms[step1, {DT -> {I$VLOAD -> 25.*^-6}}]

Out[6]=

Display complexity information of the simplified system. Note that the number of terms decreased, while the number of equations stayed the same.

In[7]:= Statistics[step2]