Data Types, Controllers, Sinks, and Components

Before continuing to use ADS Ptolemy, let's look at some of the concepts you may have questions about and introduce the signal processing components that ADS Ptolemy uses.

Representation of Data Types

ADS Ptolemy components have stems of different colors and thicknesses that are based on the data type (this differs from Analog/RF Systems components). The following table lists the data types.

Note For some applications, particularly those using timed components, data types can be thought of as signal types. Regardless of the terminology, packets of data are passed from one component to another.

Data Type Representation

Data Type	Stem Color	Stem Thickness
Scalar Fixed Point	Magenta	Thin
Scalar Floating Point (Real)	Blue	Thin
Scalar Integer	Orange	Thin
Scalar Complex	Green	Thin
Scalar Timed	Black	Thin
Matrix Fixed Point	Magenta	Thick
Matrix Floating Point (Real)	Blue	Thick
Matrix Integer	Orange	Thick
Matrix Complex	Green	Thick
Any Type	Red	Thin

The following figure shows the thicker stem width associated with matrix data compared to the thinner stem width associated with scalar data.

Matrix Data (Thick Lines) Versus Scalar Data (Thin Lines)

Components have single or multiple arrowheads at inputs or outputs.

• Single arrowheads carry one distinct signal.
• Multiple arrowheads carry more than one distinct signal.

For example, a multiple input multiplier component has multiple arrowheads at the input and a single output arrowhead, as shown in the previous figure.

BusMerge items can be used to connect multiple signals to a component when the signal order must be specified. Similarly, BusSplit items can be used to split signals to multiple outputs.

Automatic or Manual Data Type Conversion

When you connect components of the same data type (color), data is copied from one component to another. If you connect components represented by different data types, such as scalar complex to scalar floating-point (real), or scalar integer to matrix integer, consider two things about conversion:

• Should I place a conversion component in the schematic or let the software automatically do the conversion?
• What will happen to my data?

Although the software will automatically convert dissimilar data types, such as complex to floating-point (real), place an appropriate converter (from the Signal Converters library) in your schematic. This acts as a visual reminder that a conversion is taking place, and also helps you decode error messages that may arise. Automatic conversion means that an appropriate converter is spliced in behind the scenes and is not shown on the schematic.

Automatic conversion is allowed among scalar data types and among matrix data types, but not between scalar and matrix data types.

For Timed pins, there are two cases when automatic splicing produces an error message:

• When either a Float (real) to Timed, Fixed to Timed, Integer to Timed, or Complex to Timed converter is placed (or spliced) in the design and there is no time step defined (via sources or other timed converters) in the design. You must define the time step at least once in your design.
• When a Complex port is connected to a Timed port. Automatic conversion from Complex to Timed is not supported. You must place a Complex to Timed converter between the ports and enter appropriate parameters.

When a scalar pin is directly connected to a matrix pin (or vice versa), without a Pack or Unpack converter, an error message is generated.

In the Numeric Matrix Library, four converters are used to pack scalar data into matrix data, such as Pack_M and PackCx_M. Similarly, four converters unpack the data (back to scalar), such as UnPk_M and UnPkCx_M. There is no automatic conversion between scalar and matrix data (or vice versa); you must place the converters where needed in your design.

What Happens During Conversion?

Most conversions do what you expect. For example, when converting from lower precision to higher precision data types, such as integer to floating-point (real), no data is lost; only the format is changed.

When converting from higher precision to lower precision data types, such as floating-point (real) to integer, the outcome is governed by your computer's math rounding rules, with the following exceptions:

• Complex to Float (Real) ADS Ptolemy calculates the magnitude and ignores the phase.
• Complex to Fixed After calculating the floating-point (real) magnitude, ADS Ptolemy converts the floating-point (real) to fixed.
• Complex to Integer After calculating the floating-point (real) magnitude, ADS Ptolemy converts the floating-point (real) to integer.

Timed Data Conversions

The Timed data type represents the time-domain signal in either carrier-modulated (complex) or real-baseband flavors. The Timed data class members are I, Q, Fc, time, plus an ADS Ptolemy member called Flavor. Flavor specifies whether the Timed data type is in a carrier-modulated or real-baseband format. When the carrier frequency is not specified (undefined) for a Timed port, an error message is generated.
You can convert between Timed and non-Timed ports by placing one of the following converters and supplying the parameters as needed:

• Timed to Complex or Complex to Timed
• Timed to Float (Real) or Float (Real) to Timed
• Timed to Fixed or Fixed to Timed
• Timed to Integer or Integer to Timed

Time-data conversion depends on the flavor of the Timed data and the carrier frequency.

For more detailed information on conversion of data types, refer to Conversion of Data Types.

Controllers

Controllers, used to control simulation, are placed unconnected any where in the schematic, and are found in the Controllers library or palette. The DF (data flow) controller controls the flow of mixed numeric and timed signals for all digital signal processing simulations within ADS. Other controllers are used to set up parameter sweeps, optimization, or statistical design. To set or modify the parameters using a dialog box, double-click the component in the schematic, or choose Edit > Component > Edit Component Parameters.

DF (Data Flow) Controller

The DF (data flow) controller is required for all simulations. Use the DF controller to control the flow of mixed numeric and timed signals for all digital signal processing simulations within ADS. This controller, together with source and sink components, provide the flexibility to control the duration of simulation globally or locally.

Important Multiple DF controllers on the schematic are not allowed. Versions of ADS Ptolemy released before ADS 1.5 allowed multiple DF controllers on the same schematic. Starting with ADS 1.5, this is no longer possible. Multiple controllers were used to simulate the same design with different DF parameters, for example with a different value of DefaultNumericStart. You can achieve the same effect by using single-point sweeps on the parameter you are interested in varying.

The DF controller dialog box has the Controls, Options, Output, Resistors, Debug, and Display tabs, which are described in the following sections.

Controls Tab

ADS Ptolemy sinks have Start and Stop parameters that control when to start and stop data collection. Sinks collect from Start to Stop, inclusively.

In numeric sinks, these numbers are unitless because they represent sample numbers. The first data that the sink receives is #0, the second is #1, etc. For example, a numeric sink with Start=3 and Stop=4 will skip the first three pieces of data and collect the next two.

In timed sinks, Start and Stop have timed units because the data has a time base. The amount of data that the sink collects is a function of both the data time base and the sink's Start and Stop parameters. For example, if Start=0 µsec, Stop=1 µsec, and the data has a time base of 2 µsec, the sink will collect 501 pieces of data.

The Controls tab contains global parameters that are the default values for the sink's start and stop parameters. Numeric sinks' start and stop parameters are set to DefaultNumericStart and DefaultNumericStop. Timed sinks' start and stop parameters are set to DefaultTimeStart and DefaultTimeStop. Default values for these DF controller values are 0, 100, 0 µsec, and 100 µsec, respectively.

Sinks can control simulation locally with their own start and stop times, or they can use the appropriate DF parameter to inherit control. By default, all sinks inherit start and stop times from the controller. You can inherit none, one, or both of the start and stop times.

Because these DF parameters function as variables inside the simulation, they can be used inside expressions or overridden in a hierarchal fashion. For example, you could set a numeric sink's parameters to Start=DefaultNumericStart and Stop=DefaultNumericStop*2.

Options Tab

The options tab has the following parameters:

DefaultSeed Enter an integer to seed the random number generator. The default is 1234567.

DefaultSeed is used by all random number generators in the simulator, except those components that use their own specific seed parameter. DefaultSeed initializes the random number generation. The same seed value produces the same random results, thereby giving predictable simulation results.

To generate repeatable random output from simulation to simulation, use any positive seed value. For the output to be truly random, enter a seed value of 0.

OutVar

Note OutVar is an obsolete parameter. Use the Output tab (refer to Output Tab) and the OutputOption controller (refer to OutputOption Controller).

OutVar is a space-separated list of variable names defined using variables and equations (VAR) components. Values are sent to the Data Display window. In the case of hierarchical designs, in order to send variables that are at a level other than the top-most level, use the complete path to the variables, which must be period (.) delimited.

Example:

OutVar="freq1 freq2 X1.amplitude X2.X4.temp"

In this case, there are four variables to be sent to the Data Display: freq1, freq2, amplitude, and temp, each separated with a space. The variable amplitude is contained in subnetwork X1, while the variable temp is contained in subnetwork X4, which in turn is contained in subnetwork X2. These subnetworks are delimited with periods.

Note ADS places a set of quotes around the OutVar variable. Do not enter your own quotes as the double set will cause simulation failure. The global character * is no longer supported.

SchedulerType The Scheduler Type enables you to run the simulation based on options from the drop-down list:

• Cluster Loop Scheduler (default) Optimized for multirate graphs with feedback cycles.
• Classical Scheduler For uni-rate graphs with cycles.
• Hierarchical Scheduler For multirate graphs with disconnected graphs.
• Multithreaded Scheduler Optimized for multiprocessor machines.
• Multirate Scheduler Optimized for large-scale or heavily multi-rate graphs.

No matter which scheduler is chosen, the simulation results will be the same. The difference is in the time and memory needed to set up and run the simulation. It's best to start with the default, and experiment with the others as needed. For more information on these schedulers, refer to How Schedulers Work.

DeadlockManager The Deadlock Manager enables you to manage design deadlocks. A deadlock occurs when a feedback loop does not have a delay in its feedback path, or when a Delay item does not initialize the proper number of signal tokens. A static schedule (required for simulation) can only be derived in a design with no schedule deadlocks.

Select the type of deadlock management from the drop-down list:

• Report deadlock (default) Indicates the design includes deadlocks.
• Identify deadlocked loop s Enables you to spot which loops are deadlocked. These loops can be highlighted on the schematic page by clicking on the error message or Status window.
• Resolve deadlock by inserting tokens Adds delays to deadlock loops and allows the simulator to proceed.

CktCosimInputs This option controls the initialization method on the input pins of Analog/RF circuits during cosimulation. The option applies initialization to all cosimulation circuit subnetworks. (Refer to Cosimulation with Analog-RF Systems for information regarding how to set up an ADS Ptolemy A/RF cosimulation.) Select the type of input initialization method from the drop-down list:

• No change (default) No special initialization.
• Initialize with zero volts Initialize the first data of all input pins to 0; basically, the first data value is discarded.
• Insert one time step delay Insert one extra data with 0 value to all input pins, delaying everything by one time step.

Output Tab

The Output tab enables you to selectively save simulation data to a dataset. For details, refer to Selectively Saving and Controlling Simulation Data.

Note that Node Voltages are supported only on A/RF controllers; therefore, you will not find this option available on the Data Flow Controller's Output tab.

Resistors Tab

The Resistors tab controls global parameters related to resistor behavior. As in the Controls tab, these parameters act as variables inside the simulation. Overriding the resistor values in a hierarchal fashion can be especially useful. For example, a large design can have a subcircuit representing a component being tested. By setting the DefaultRTemp inside the Data Flow controller to -273.15, and placing a VAR block with a DefaultRTemp setting inside the subcircuit, you can easily add resistor noise to the subcircuit only.

DefaultRIn is the default input impedance of timed components; its value is 50 ohms.

DefaultROut is the default output impedance of timed components; its value is 50 ohms.

DefaultRLoad is the default input impedance of timed sinks and the default impedance of solitary resistors (the R component); its value is 1.0e18 ohms, representing an infinite load.

DefaultRTemp is the default temperature of resistors; its value is -273.15 Celsius (0 K), so by default there is no thermal noise.

Debug Tab

The Debug tab can be used to provide the ability to debug your design and its custom components.

Schedule Log File enables you to specify the file name for a log file. After simulation, the log file you specified will be generated under the / data directory of the project. It will log the firing schedule of components in your design.

Profile Times File enables you to specify the file name for a file containing simulation information. After simulation, the file will be located under the / data directory of the project. It provides run-time information for components in your design during simulation. For example, information may include the number of times a component is fired or the average time.

Display Tab

From the Display tab, you can choose which parameters to display on the schematic. By default, only the start and stop parameters are selected; choose which parameters to display by selecting or unselecting parameters.

OutputOption Controller

Description: Output Option for Dataset Templates
Library: Controllers

Parameters

Name	Description	Default	Type	Range
DatasetTemplate	Dataset Template name (repeatable)		string

Notes/Equations

1. The OutputOption controller is used to specify the data display template(s) for Wireless Test Bench (WTB) used in RFDE.
2. All listed data display template(s) will be automatically inserted into an Autoplot data display window in RFDE after simulation.
3. The string value of DatasetTemplate should be the name of only one data display template file and should not contain the data display template file extension (.ddt).
4. To list more than one template name, use the Add button on the component dialog box to add additional DatasetTemplate parameters, each of which should have a string value for only one template.
5. A blank space (" ") value for DatasetTemplate will be ignored.

WTB Controller

Description: Controller for Wireless Test Bench
Library: Obsolete (not to be discontinued) Controllers

Parameters

There are no parameters for this controller.

Notes/Equations

Note This controller is obsolete for new designs. (It is available only for compatibility with designs created with ADS 2005A or earlier.) There are no plans to remove this controller from future ADS releases; however, enhancements or fixes of any existing defects will not be made. Please use the revised method for creating wireless test benches described in Wireless Test Bench Designs.

1. The WTB controller is used to verify a wireless test bench design created in ADS before exporting the design to RFDE as a WTB model.
   For details about creating these designs, see appendix A, "Creating Wireless Test Bench Designs for RFDE" in the ADS Ptolemy Simulation documentation for ADS 2005A or earlier.
2. The WTB model created in ADS is a subcircuit that must contain output pins and input pins followed by EnvOutShort or EnvOutSelector. The WTB model subcircuit must also have a DF controller with the correct setup. The WTB model simulates a RFIC Design Under Test (DUT) and reads the data back from the DUT to do complex measurements.
3. The WTB subcircuit created in ADS should be verified before exporting the WTB design to RFDE. To verify the WTB subcircuit open a new DSP schematic window, and add a WTB controller along with the instance of the WTB model subcircuit, a DUT, and an Envelope controller. The WTB controller enables a cosimulation between the Envelope controller and the DF controller inside the WTB model subcircuit.
4. The Envelope controller must be added along with an instance of the DUT subcircuit created using Analog/RF components. The Envelope controller can be added to the WTB verification design (DSP schematic) by opening an Analog/RF schematic window, adding an Envelope controller in this window, then copy and paste the Envelope controller into the WTB verification design window.
5. The WTB simulation in ADS will ignore the OutputOption controller that has been placed in the WTB subcircuit (see OutputOption Controller). This means that the data display window with the templates defined in the OutputOption controller will not be opened automatically in ADS. These templates open only in RFDE.

VarEqnCheck

Description: Check value range from a variable or expression
Library: Controllers

Parameters

Name	Description	Default	Type	Range
ParameterRange	Boolean expression for the parameter range check (value of 1 means ParameterValue within range limits)	X>=1	int
ParameterValue	Optional value that can be reported when a message is to be displayed	X	real
ReportValue	Report parameter value	NO	query	NO, YES
Type	Range check message type	Warning	enum	Warning, Status message, Initialization error, Abort simulation error, Standard
Message	Message to display if ParmeterRange evaluates to 0	`X is out of range, it should be >=1'	string

Notes/Equations

1. Use VarEqnCheck to check the value range limits of a parameter defined either in a VAR item (variable or expression) or defined as a subnetwork parameter.
2. ParameterRange performs parameter value range test on the value defined by ParameterValue. ParameterRange should be a boolean expression that evaluates to 1 when the range test is successful. A range test is considered to be a failure when ParameterRange is zero and results in display of the message defined by Message.
3. ReportValue , when set to YES , results in display of the ParameterValue along with the Message when the ParameterRange is zero.
4. Type is the type of message displayed.
5. When Type is Warning , then the range test is performed during simulation. A range test failure ( ParameterRange =0) results in display of the Message in the Simulation Message window (and optionally ParameterValue when ReportValue = YES ) and continuance of the simulation.
6. When Type is Status message , then the range test is performed during simulation. A range test failure ( ParameterRange =0) results in display of the Message in the Simulation Status window (and optionally ParameterValue when ReportValue = YES ) and continuance of the simulation.
7. When Type is Initialization error , then the range test is performed during simulation initialization before simulation begins. A range test failure ( ParameterRange =0) results in display of the Message in the Simulation Message window (and optionally ParameterValue when ReportValue = YES ). The simulation will continue for the remainder of the simulation initilization and will quit after all initialization errors are detected.
8. When Type is Abort simulation error , then the range test is performed during simulation. A range test failure ( ParameterRange =0) results in display of the Message in the Simulation Message window (and optionally ParameterValue when ReportValue = YES ) and simulation will quit.

Sources and Sinks Control the Simulation

ADS Ptolemy simulation is controlled by the sources and sinks you place on your schematic. There must be at least one source or sink that is controlling the simulation. All sinks and many sources have a ControlSimulation parameter that is set to YES or NO. Controlling sinks and sources keep the simulation running; non-controlling sinks and sources do not.

Sinks

Sinks are components with no outputs. When a sink controls the simulation (ControlSimulation=YES), data collection always begins at the input sample with an index value equal to the value of the Start time parameter. The data collection ends with an index value equal to the value of the Stop time parameter. (One or both of the Start and Stop times might be inherited from the Data Flow controller.) By default, a sink's ControlSimulation parameter is set to YES. When a sink is not controlling the simulation (ControlSimulation=NO), it will start collecting data at Start, then collect as much data as the simulation produces. Consider the following example:

As shown, both sinks will collect 101 data samples (0 to 100 inclusive). They are both controlling sinks so they will obey their start and stop index times. Because of the DownSample, sink N2 will receive more data but it will not collect it.

Changing one of the sinks ControlSimulation parameters to NO will cause N2 to collect twice as much data as N1. If N1 is the controller, then it will collect 101 samples, and N2 will collect 202. If N2 is the controller, then it will collect 101 samples, and N1 will collect 50.

This example demonstrates a useful way to design a schematic with multiple sinks. Choose one sink to control the simulation, and set all other sinks' ControlSimulation parameters to NO. In this manner, your sinks will collect appropriate amounts of data according to the multirate characteristics of your schematic.

Sources

Sources are components with no inputs. Sources that read from files, instruments, and data sets also have a ControlSimulation parameter. By default, its value is NO. When a source is controlling the simulation, it will keep the simulation running long enough to output all its data. Controlling sources can be used to create designs that process all the data in a file, as shown next.

In this example, the SDFRead component is controlling the simulation, and the TimedSink parameter is not in control. The TimedSink will collect all the data available in the file. This example demonstrates another useful way to design schematics: control the simulation with a source, and set all the sinks' ControlSimulation parameters to NO.

In the example, if both components' ControlSimulation parameters were flipped so that only the TimedSink was in control, then it would collect enough data to meet its Start and Stop parameters. If that were more data than was available in the file, then the SDFRead component would repeat its data or zero pad according to its Periodic parameter. If that were less data than was available in the file, then the SDFRead would not output the entire file.

It's possible to set both components' ControlSimulation parameters to YES. In that case, and if the file had more data than the TimedSink's Start and Stop required, then the SDFRead would output the entire file, but the TimedSink would ignore any data received after its Stop.

ADS Ptolemy Components

The component libraries available for use with signal processing designs using the ADS Ptolemy simulator are listed in the following table. Reference information for each component is available by choosing Help, either from the parameters dialog box for a specific component, or from the Help menu.

Get to know the available components by choosing Insert > Component > Component Library , resizing the dialog box so you can read the complete names, and browsing through the list.

Note If you have purchased and installed ADS Design Library products, such as the CDMA, cdma2000, GSM, EDGE, DTV, 1xEV, TDSCDMA, WLAN, or W-CDMA3G design libraries, they will be displayed in the list, in alphabetical order.

ADS Ptolemy Component Libraries

Library	Summary of Contents
Antennas & Propagation	Components for radio channel, including antennas and propagation models. The channel models provide built-in functionality based on various standards: 1xEV, 3GPP, DTV, GSM, TDSCDMA, CDMA, WLAN.
Circuit Cosimulation	Items used to set up cosimulation with analog/RF circuits.
Common Components	A factory list of the most commonly-used components.
Controllers	Items that control simulation parameters.
HDL Blocks	HDL cosimulation components.
Instruments	Components used to link data to instruments, such as the 89600 Vector Signal Analyzer.
Interactive Controls and Displays	Components that control and interactively display real-time simulation results. Data is not saved.
Numeric Advanced Comm	Components that provide functions for simulation of advanced communication systems based on the latest communication technologies including wireless metropolitan access networks (WMAN), wireless local access networks (WLAN), and wireless personal access networks (WPAN).
Numeric Communications	Components that perform numeric communications functions such as ADPCM coder, QAM encoder, Viterbi decoder, modulation, demodulation, scrambler, spreader.
Numeric Control	Items that manipulate data flow during simulation: commutators, multiplexers, demultiplexers, upsamplers, and forks.
Numeric Fixed Point DSP	Bit-accurate DSP models (adders, registers, etc.) with behavioral C++ simulation code.
Numeric Logic	Contains Boolean operators, such as and, or, equals, greater than, etc.
Numeric Math	Components that perform math functions, such as adders, multipliers, integrators, log, sine, cosine.
Numeric Matrix	Components that receive and/or produce vector or matrix signals at their input and output, such as add and multiply. Also contains MATLAB components and components used for converting scalar to matrix.
Numeric Signal Processing	Components that perform basic discrete-time DSP functions, such as FIR filter, IIR filter and adaptive filter, and DTFT.
Numeric Sources	Contains sources (items having output only) that produce numeric signals. This includes sources that output scalar, matrix, and random signals.
Numeric Special Functions	Miscellaneous items. Typically nonlinear operations such as quantizing, limiting, or triggering on input signals.
Signal Converters	Converts signal (data) types, from one type to another, for example, CxToFloat (complex to floating-point (real)). Others include integer, fixed, or timed.
Sinks	Data collection items or data processed as measurements, such as numeric sink, BER sinks, or EVM sink.
Timed Data Processing	Data processing components that operate on time-domain baseband waveforms, e.g., multilevel symbol coders and converters, IQ data coders.
Timed Filters	Time-domain lowpass and bandpass analog filters for filtering baseband or RF signals.
Timed Linear	Various linear operations for time-domain analog baseband and RF signals, e.g., waveform delay, split, sum, sample, switch.
Timed Modem	Analog RF modulators, demodulators, and carrier recovery for AM, FM, PM, QAM, QPSK, GMSK, MSK, DQPSK, and Pi/4 DQPSK formats.
Timed Nonlinear	Various nonlinear time-domain operations for time-domain analog baseband and RF signals, e.g., nonlinear gain, RF mixers, RF multipliers, rectifiers, signal sampling, or phase detectors.
Timed RF Subsystems	RF subsystem components, such as RF combiner, RF modulator, or RF demodulator.
Timed Sources	Time-domain signal generators for baseband and RF signals, e.g., AM, FM, PM, QAM, clock, sinusoid, pulsed, or video.