%% HDL Code Generation for the T Equivalent Transformer Inrush Current Model
% The following demo illustrates the support for nonlinear circuit
% components in the Simscape HDL Workflow Advisor. Specifically, this model
% uses a nonlinear inductor to simulate the inrush current into a
% transformer.
%
% The transient response of a transformer during loading can produce inrush
% currents with magnitudes several times larger than the steady state
% current. Therefore, it is imperative to know the magnitude of the inrush
% current.
%
% As the windings and iron cores of transformers behave nonlinearly,
% an accurate model of the inrush current into a transformer includes
% nonlinear elements. However, nonlinear blocks such as nonlinear capacitors or nonlinear inductors consume significantly large resources and may not even synthesize on the target FPGA device. These blocks are therefore not supported with the Simscape HDL Workflow Advisor.
%
% To remove this constraint, when you run the Simscape HDL Workflow Advisor, use the _Reduce Model Order_ task to linearize the nonlinear blocks. This example illustrates how you can run the Simscape HDL Workflow Advisor for a Simscape model that contains nonlinear components. Specifically, this example illustrates how to linearize a nonlinear inductor that simulates the inrush current into a model, and then generate HDL code for the implementation model.

%% T Equivalent Circuit
% The T equivalent circuit is a simplified model of a two-winding
% transformer. To open the T equivalent circuit model for this demo, enter
% the following commands in the MATLAB command window:


%   Copyright 2020 The MathWorks, Inc.

load_system('sschdlexNonlinearTransformerExample')
open_system('sschdlexNonlinearTransformerExample')

%%
% The resistors and the inductors in the top branch of the model
% correspond to leakage from the primary and secondary windings and the
% resistor and inductor in the parallel branch corresponded to leakage from
% the transformer core.
%
% The model uses a nonlinear inductor to model the leakage from the
% transformer core. A comparision of this model with a linear model be
% found in _LinearVNonlinearTransformer.slx_. The significance of nonlinearity on the
% calculated inrush current can be shown in the plot below
%

%%
% <<nonlinear_transformer_comparison.jpg>>
%

%%
% The blue line is a T equivalent circuit using a nonlinear inductor
% and the yellow line is using an equivalent linear inductor. As seen in
% the plot, the nonlinear inductor more accurately captures the magnitude
% of the inrush current.

%% Run Simscape HDL Workflow Advisor
% 1. To generate an HDL implementation of the transformer model from which you
% can generate HDL code, use the Simscape HDL Workflow Advisor. To open the
% Advisor, run the following command:
%
%   sschdladvisor('sschdlexNonlinearTransformerExample')

%%
% 2. To run the Advisor, right-click the *Reduce Model Order* task and select
% *Run to Selected Task*. The *Reduce Model Order* task linearizes the nonlinear inductor block. Nonlinear blocks consume large amount of resources and may not even synthesize on the target FPGA device. Linearization removes this constraint by converting the block to a linear approximation which results in explicit state space equations.

%%
% 3. Select the checkbox *Linearize* and the
% checkbox *Generate validation logic for the implementation model* and change the default value of *Rs* to 20,000. 

%%
% 
% <<nonlinear_transformer_simscape_advisor.png>>
% 
%%
% Running this task generates a validation file named
% _vldgmLinearized_sschdlexNonlinearTransformerEx.slx_. Open this file with
% the following command:

%%
%   open_system('vldgmLinearized_sschdlexNonlinearTransformerEx')

%%
%
% <<nonlinear_transformer_linearized_validation.PNG>>

%%
% Use the validation model to verify that the linearization of the
% nonlinear inductor does not change the behavior of the original plant.

%%
% 
% <<nonlinear_transformer_reduction_error.png>>
%

%%
% As shown in the above plot, the error between the behavior of the
% linearized plant the original plant is minimal.

%% 
% 4. Right-click the *Generate implementation model* task and select
% *Run to Selected Task*.

%%
% 
% <<nonlinear_transformer_workflow_advisor_2.png>>
% 

%%
% Running this task generates HDL implementation model called _gmStateSpaceHDL_sschdlexNonlinearTransformerEx.slx_. Open this file with the following command:

%%
%   open_system('gmStateSpaceHDL_sschdlexNonlinearTransformerEx')

%%
%
% <<nonlinear_transformer_hdl_subsystem_validation.PNG>>

%%
% Use the validation logic inside the model to verify that the linearization of the
% nonlinear inductor does not change the behavior of the original plant.

%%
% 
% <<nonlinear_transformer_current_error.png>>
% 

%%
% As seen in the above plot, the error in the inrush current between the
% linearized Simscape system and the equivalent HDL subsystem is small.

%% Generate HDL Code and Validation Model
% The HDL model and subsystem parameter settings are saved using the following commands:
%%
%   hdlsetup('gmStateSpaceHDL_sschdlexNonlinearTransformerEx')
%   hdlsaveparams('gmStateSpaceHDL_sschdlexNonlinearTransformerEx')

%%
% The model uses single data types and generates HDL code in native floating-point mode. To allocate enough delays for the operators, the model uses clock-rate pipelining in conjunction with a large value for the Oversampling factor. An Oversampling factor of 100 and the clock-rate pipelining optimization is saved on this model.
%
% For more information, see:
%%
% * <https://www.mathworks.com/help/hdlcoder/ug/clock-rate-pipelining.html Clock-Rate Piplelining>
% * <https://www.mathworks.com/help/hdlcoder/ug/oversampling-factor.html Oversampling Factor>
% * <https://www.mathworks.com/help/hdlcoder/ug/unable-to-allocate-delays-in-native-floating-point-mode.html Allocate Sufficient Delays for Floating-Point Operations>
%%
% Before you generate HDL code, it is recommended to enable generation of
% the validation model. The validation model compares the output of the
% generated model after code generation and the original model. To learn
% more see,
% <https://www.mathworks.com/help/hdlcoder/ug/generated-model-and-validation-model.html Generated Model and Validation Model>.
% Run these commands to save validation model generation settings on your
% Simulink Model:

%%
%   HDLmodelname = 'gmStateSpaceHDL_sschdlexNonlinearTransformerEx';
%   hdlset_param(HDLmodelname,'TargetDirectory','./');
%   hdlset_param(HDLmodelname, 'GenerateValidationModel', 'on');

%%
% To generate HDL code, run the following command:

%%
%   makehdl('gmStateSpaceHDL_sschdlexNonlinearTransformerEx/HDL Subsystem')

%%
% The generated HDL code and validation model are saved in the working
% directory. The generated code is saved as _HDL_Subsystem_tc.vhd_. To open
% the validation model, click the link to
% _gmStateSpaceHDL_sschdlexNonlinearTransformerEx_HDL_vn1_slx_ in the code generation
% logs in the Command Window. Open the Compare block at the output of
% the _HDL_Subsystem_vn1_ subsystem of the validation model. Then click
% the block labeled _Double click to turn 'on/off' all scopes_. Two scope
% plots should appear. Then run the simulation and see a comparison of the
% inrush current from the simscape system and generated HDL system.

%%
%
% <<nonlinear_transformer_hdl_validation_comparison.png>>
%

%%
% In the top plot, the top graph represents the output of the generated
% model, and the middle graph represents the output from the HDL
% implementation model. The bottom graph displays the
% error which can be seen to be zero.
% 
% Optionally, you can deploy the HDL code on a Hardware platform. For more
% infomation, see
% <https://www.mathworks.com/help/hdlcoder/ug/deploy-plant-model-to-speedgoat-io-modules.html
% Deploy Simscape plan models to Speedgoat FPGA IO modules>.
