ee_getHarmonics

Return harmonic orders, magnitudes, and fundamental frequency

Syntax

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

 ee_getHarmonics(loggingNode)

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

ee_getHarmonics(loggingNode,valueIdx)

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

ee_getHarmonics(loggingNode,valueIdx,tOfInterest)

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest)

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

 ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest,...

offsetOfInterest)

[harmonicOrder,harmonicMagnitude,fundamentalFrequency]
=...

 ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest,...

offsetOfInterest,nHarmonic)

Description

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode) calculates the harmonic orders, magnitudes, and fundamental frequency of a simscape.logging.Node of an AC or periodic variable.

The function finds the points in the i^th signal (valueIdx) where the Simscape™ log crosses a threshold (offsetOfInterest). It uses the crossing points to find the required number of periods (nPeriodOfInterest) preceding the specified time (tOfInterest). Then it inputs the down-selected data to the Goertzel algorithm, which calculates the harmonic magnitudes up to and including the required number of harmonics (nHarmonic).

You enter the input arguments in a specific order. The Simscape logging node input argument is required. All other input arguments are optional and have default values. If you are specifying a value for a subsequent optional input argument, enter [] to use the default value for an optional input argument.

You can use the ee_plotHarmonics function to obtain a bar chart from the same input arguments. You can use the outputs of this function as inputs to the ee_calculateThdPercent function to calculate the total harmonic distortion (THD) percentage.

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode,valueIdx)uses the index into value data.

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode,valueIdx,tOfInterest) uses the simulation time.

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest) uses the number of periods of fundamental frequency.

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest,... offsetOfInterest) uses the DC offset.

[harmonicOrder,harmonicMagnitude,fundamentalFrequency] =... ee_getHarmonics(loggingNode,valueIdx,tOfInterest,nPeriodOfInterest,... offsetOfInterest,nHarmonic) uses the number of harmonics.

example

Examples

Analyze Using Default Values

This set of function arguments uses the Simscape logging node simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I, which contains data from a three-phase current. The function analyzes the default signal, which is the first, or a-phase, signal at the final simulation time. The function uses the default values of 12 for the number of periods of the signal, 0V for the signal bias, and 30 for the number of harmonics.

openExample("simscapeelectrical/SixPulseHarmonicsExample")
sim('SixPulseHarmonics')
[~,harmonicMagnitude,~]= ee_getHarmonics(simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I);
%harmonicMagnitude stores the peak values of the harmonics. To get the RMS values, divide by sqrt(2)
harmonicMagnitude./sqrt(2)

ans =

   1.0e+03 *

  Columns 1 through 14

    0.0000    1.3759    0.0000    0.0000    0.0000    0.1548    0.0000    0.0748    0.0000    

    0.0000    0.0000    0.0602    0.0000    0.0407

  Columns 15 through 28

    0.0000    0.0000    0.0000    0.0357    0.0000    0.0266    0.0000    0.0000    
    
    0.0000    0.0239    0.0000    0.0187    0.0000    0.0000

  Columns 29 through 31

    0.0000    0.0170    0.0000

Analyze Using Specified Values

This set of function arguments uses the Simscape logging node simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I, which contains data from a three-phase current. The function analyzes the second, or b-phase, signal at a simulation time of 0.5 s. The function uses 10 periods of the signal, assuming a bias of 1V. The function analyzes 15 harmonics.

openExample("simscapeelectrical/SixPulseHarmonicsExample")
sim('SixPulseHarmonics')
[~,harmonicMagnitude,~]= ee_getHarmonics(simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I,2,0.5,10,1,15);
%harmonicMagnitude stores the peak values of the harmonics. To get the RMS values, divide by sqrt(2)
harmonicMagnitude./sqrt(2)

ans =

   1.0e+03 *

  Columns 1 through 15

    0.0000    1.3761    0.0008    0.0005    0.0006    0.1544    0.0000    0.0748    0.0003    

    0.0002    0.0003    0.0599    0.0001    0.0407    0.0004

  Column 16

    0.0003

Analyze Using Default and Specified Values

This set of function arguments uses the Simscape logging node simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I, which contains data from a three-phase current. The function analyzes the first, or a-phase, signal at a simulation time of 0.5 s. The function uses 12 periods of the signal, assuming a bias of 1V. The function analyzes the default number, 30, of harmonics.

openExample("simscapeelectrical/SixPulseHarmonicsExample")
sim('SixPulseHarmonics')
[~,harmonicMagnitude,~]= ee_getHarmonics(simlog_SixPulseHarmonics.Sensing_current.Current_Sensor.I,[],0.5,[],1);
%harmonicMagnitude stores the peak values of the harmonics. To get the RMS values, divide by sqrt(2)
harmonicMagnitude./sqrt(2)

ans =

   1.0e+03 *

  Columns 1 through 15

    0.0000    1.3759    0.0000    0.0000    0.0000    0.1548    0.0000    0.0748    0.0000 
 
    0.0000    0.0000    0.0602    0.0000    0.0407    0.0000

  Columns 16 through 30

    0.0000    0.0000    0.0357    0.0000    0.0266    0.0000    0.0000    0.0000    0.0239   

    0.0000    0.0187    0.0000    0.0000    0.0000    0.0170

  Column 31

    0.0000

Input Arguments

collapse all

`loggingNode` — Simscape logging node
1-by-1 simscape.logging.Node

Simscape logging node, specified as a 1-by-1 simscape.logging.Node. You create a simscape.logging.Node by running a simulation with Simscape logging enabled. For information, see Enable Simscape Data Logging for the Whole Model.

Example: simlog.Load.V

The Simscape logging node simlog.Load.V contains data from a three-phase voltage.

`valueIdx` — Index into value data
`1` (default) | scalar

Index into value data, specified as a scalar. Specifies the i^th variable of interest in the Simscape log.

Example: 2

Specify the b-phase, which is the second signal from a three-phase voltage.

Example: []

Use [] to specify the default value of 1. The a-phase, which is the first signal from a three-phase voltage, is the default signal of interest.

`tOfInterest` — Simulation time
final time in Simscape log (default) | scalar

Simulation time of interest for harmonic analysis, specified as a scalar.

Example: 0.5

Specify a 0.5 s simulation time.

`nPeriodOfInterest` — Number of periods
`12` (default) | scalar

Number of periods of fundamental frequency to be included in harmonic analysis, specified as a scalar.

Example: 10

Specify 10 periods of the signal.

`offsetOfInterest` — DC offset
`0` (default) | scalar

DC offset in the input signal, specified as a scalar. The function uses this value to find the periods of interest.

Example: 1

Specify a bias of 1 V for the signal.

`nHarmonic` — Number of harmonics
`30` (default) | scalar

Number of harmonics to include in analysis, specified as a scalar.

Example: 15

Specify that the number of harmonics to be analyzed is 15.

Output Arguments

collapse all

`harmonicOrder` — Harmonic order
vector

Harmonic orders from 0 up to and including the number of harmonics used in the analysis, returned as a vector.

`harmonicMagnitude` — Harmonic magnitude
vector

Harmonic magnitudes from the 0^th harmonic up to and including the number of harmonics used in the analysis, returned as a vector.

`fundamentalFrequency` — Fundamental frequency
scalar

Fundamental frequency over the range of the down-selected input data, returned as a scalar.

Limitations

This function requires that you use a fixed-step solver for the Simscape Electrical™ Power Systems network that you are analyzing. To specify a fixed-step solver for the physical network, use one of the configuration combinations in the table.

Configuration Combination	Global Solver Configuration	Local Solver Configuration
Global variable-step with local fixed-step	Set Type to `Variable-step`	Enable the options to Use local solver and Use fixed-cost runtime consistency iterations
Global and local fixed-step	Set Type to `Fixed-step`	Enable the options to Use local solver and Use fixed-cost runtime consistency iterations
Global fixed-step	Set Type to `Fixed-step`	Clear the option to Use local solver

This function uses threshold crossing points to determine the fundamental frequency of the data. If your input data is noisy or crosses the threshold more frequently than half of the fundamental period, filter it before you use this function to analyze it.
This function requires a minimal number of periods. If the minimal number is not met, the function generates a warning message. To increase the number of periods, use one or both of these methods:
- Increase the simulation time.
- Increase the switching frequency.

Version History

Introduced in R2014a

ee_getHarmonics

Syntax

Description

Examples

Analyze Using Default Values

Analyze Using Specified Values

Analyze Using Default and Specified Values

Input Arguments

`loggingNode` — Simscape logging node
1-by-1 simscape.logging.Node

`valueIdx` — Index into value data
`1` (default) | scalar

`tOfInterest` — Simulation time
final time in Simscape log (default) | scalar

`nPeriodOfInterest` — Number of periods
`12` (default) | scalar

`offsetOfInterest` — DC offset
`0` (default) | scalar

`nHarmonic` — Number of harmonics
`30` (default) | scalar

Output Arguments

`harmonicOrder` — Harmonic order
vector

`harmonicMagnitude` — Harmonic magnitude
vector

`fundamentalFrequency` — Fundamental frequency
scalar

Limitations

Version History

See Also

Apps

Blocks

Functions

Objects

Topics

ee_getHarmonics

Syntax

Description

Examples

Analyze Using Default Values

Analyze Using Specified Values

Analyze Using Default and Specified Values

Input Arguments

loggingNode — Simscape logging node 1-by-1 simscape.logging.Node

valueIdx — Index into value data 1 (default) | scalar

tOfInterest — Simulation time final time in Simscape log (default) | scalar

nPeriodOfInterest — Number of periods 12 (default) | scalar

offsetOfInterest — DC offset 0 (default) | scalar

nHarmonic — Number of harmonics 30 (default) | scalar

Output Arguments

harmonicOrder — Harmonic order vector

harmonicMagnitude — Harmonic magnitude vector

fundamentalFrequency — Fundamental frequency scalar

Limitations

Version History

See Also

Apps

Blocks

Functions

Objects

Topics

`loggingNode` — Simscape logging node
1-by-1 simscape.logging.Node

`valueIdx` — Index into value data
`1` (default) | scalar

`tOfInterest` — Simulation time
final time in Simscape log (default) | scalar

`nPeriodOfInterest` — Number of periods
`12` (default) | scalar

`offsetOfInterest` — DC offset
`0` (default) | scalar

`nHarmonic` — Number of harmonics
`30` (default) | scalar

`harmonicOrder` — Harmonic order
vector

`harmonicMagnitude` — Harmonic magnitude
vector

`fundamentalFrequency` — Fundamental frequency
scalar