The File-Defined Piecewise Linear Source (FDPWL) models a Piecewise Linear (PWL) voltage or current source with data points defined in one or more data files. The source waveform definition can be defined by referencing a single file, or, one or more files can be referenced at data points defined by other files. When referencing multiple data files, very complex waveforms can be defined, as the points of sub-files are inserted at the time point in the parent file. Another common use for the FDPWL source is driving a circuit under simulation with actual oscilloscope data captured from a lab experiment.
Source definition files are simple text files organized in lines. Each line in a file represents a time-value point pair delimited either by white spaces or by commas in the style of CSV-format. The source definition files can be stored as physical files on disk or as embedded files in the F11 window. The editing dialog allows you to load the file content from disk or the F11 window, modify the file content, and save the file to either disk or to the F11 window.
In this topic:
|Model Name:||File-Defined PWL Source (FDPWL)|
|Simulator:||This device is compatible with the SIMPLIS simulator.|
|Parts Selector Menu Location:|
|Model File:||none, the FDPWL is a SIMPLIS primitive model|
|Multiple Selections:||Multiple devices can be selected and edited simultaneously.|
Each File-Defined PWL Source has four source parameters, one of which stores the path to the source definition file relative to the file path of the schematic or schematic component file. These source parameters are stored on the symbol, and the file can be stored on disk or in the schematic's F11 window. The source parameters and top-level file name can be edited by double clicking on the source symbol. The top-level file content can also be edited using the dialog, and changes to the file content are saved only when the Ok button is clicked. Clicking the Cancel button will not modify the file nor the source parameters.
|Source delay||s||The time delay between t=0 to the first time point in the file. All data points are time shifted by this delay. If the source delay is positive, the net effect is as if the source has been time shifted to the right along the time axis. If the source delay is negative, the net effect is as if the source has been time shifted to the left along the time axis.|
|Periodic source?||none||If checked, the source definition repeats forever.|
|Active only during transient after POP?||none||All PWL sources in SIMPLIS are idle during the POP and AC analyses. If this checkbox is checked, the FDPWL source will also be idle during any transient analysis which is run without a preceding POP analysis. If unchecked, the source will be active for any transient analysis with or without a preceding POP analysis.|
Each data file has three options:
|File format||The file format can be tab or comma delimited. Select your desired output format from the list of choices.|
|Repeat count||The source file can be defined to repeat from 0 to 1000 times.|
|Shift first data point to t=0?||The first point in a source definition file must be at t=0. Often oscilloscope data has time points which are negative in value, indicating these time points occur before the oscilloscope trigger time point. By checking this box, you can use the oscilloscope data and SIMPLIS will shift all data points in this file by the same amount in the simulation so that the first data point is equivalent to occur at time=0. See the Oscilloscope Waveform Example for details.|
The file options are stored on a file line which begins with the text "START_DATA". When loading the data file, the dialog automatically reads the file's START_DATA line and configures the file options controls. When you make changes to the file option controls, the dialog automatically changes the START_DATA line in the table. When you click Ok on the dialog, the file will be updated with the modified content, including the changes to the START_DATA line. The START_DATA line will be explained in detail in the following section on File Syntax.
Files saved to the F11 window have more restrictive file names than files saved on disk. F11 window filenames must be less than 64 characters and the file name can be made up of upper and lower case alphabet characters (A-Z and a-z), digits (0-9), the dollar sign ($), the period (.), the underscore (_), the dash (-), and the tilde (~) characters. Furthermore, a file name for an embedded data file must have at least one alphabet character, either upper or lower case, and it must not begin with the tilde character. It is very important to note that spaces are not allowed in embedded filenames. For a real physical data file saved to disk, its file name/path name convention follows what is dictated by the Operating System. For most cases, the dialog will not allow you to enter an F11 window filename which doesn't match this pattern. This is especially obvious when attempting to enter a space in the F11 window filename. In addition, all file names are treated in a case insensitive way. So a file named "Abc" and another file named "abc" are considered to have the same file name when SIMPLIS is searching for the data definition files.
The file syntax is described in this section. For the most part, files composed of numerical time-value points in two columns can be used as data files. The main exception is the special START_DATA line described in the following section.
Each referenced data file is processed one line at a time. If the first non-white space character in a line is an asterisk '*', the entire line is treated as a comment. Empty lines are also ignored. Each non-comment and non-empty line is considered to be made up of time-value fields separated by white spaces or commas. The exception to this rule is the special START_DATA line, which is described next.
For the remaining of the data file after the START_DATA line, each non-comment and non-empty line is expected to define a data point.
Time values can be any real numbers. In this context, real numbers are integers or floating-point numbers followed by possibly valid engineering prefixes.
Each referenced data file must satisfy the following rules:
The source amplitude value located in the second column can be a real number or it can be a reference to another data file. If the source value is a real number, the corresponding data point is considered a "simple data point." If the source value of a data point references another data file, the data point is considered a "super data point." For example, if the second and fourth data points of "four_pulses" are changed to super data points, the content of the "four_pulses" would read like the following:
As can be seen in this example, a super data point defines its source value in the following format: file="file name or path name of the file to be referenced" where the file name or path name is enclosed in matching double quotes. Super data point file references can be added using the Select... buttons located in the third column of the file contents table under the File column header. Super data point file references which refer to files located in the schematic's F11 window cannot be selected using the Select... button. Instead, you can hand-type the file name into the second column making sure to start the super data point file reference with file=" and ending the reference with a double quote character. Both the filename and the file= text are not case sensitive. In case the referenced data file exists both on disk and in the F11 window, the simulation will use the file located in the F11 window.
In searching for the referenced data files, SIMPLIS first searches for an embedded data file with a matching file name from the current circuit/subcircuit. If that fails, SIMPLIS searches for a real physical data file with a matching file/path name. An embedded data file can reference either an embedded data file or a real physical data file. But a real physical data file is allowed to reference another real physical data file but not an embedded data file.
Each FDPWL source can have up to 5 levels of data file references. The data file directly referenced on the device instantiation statement for the source is considered the first level of data file reference. In the above example there are two levels of reference, although the top level references two different data files. Since both "ringing_pos.txt" and ringing_neg.txt" contain only simple data points, these files are the lowest level of the hierarchy.
The effective source definition for a FDPWL source defined by a single data file is simple - only the points in the file are used to define the source. When additional data files are referenced by super data points, the source definition becomes much more complex. When a data file is referenced by a super data point, the points for the referenced file are inserted into the parent file definition starting at the time value of the super data point. The effective source definition is the set of time-value data points after all super data points have been inserted into the each parent data file where the points are referenced. This brings up the possibility that the parent file has a data point which occurs at a time before all of the super data points have been included in the parent file definition. In this case, the parent data point will be used, and the remaining points in the super data point file will be ignored. See the Truncated Super Data Point Example below.
The syntax of the points defined in the table can be checked at any time using the Check File Syntax button. Only the points in the table are checked for syntax, the data files referenced in the super data point are not opened and checked for syntax. If the points defined in the table have errors, the text in the erroneous rows will be changed to a red font. When the mouse pointer is hovered over the red text, a pop-up hint box describing the error will open. For example, the time value of a data point must be greater than or equal to the time value of the previous data point. For example, if a data point is entered with a time value less than the previous time value and the syntax is checked, the message displayed when hovering the mouse pointer over the line with the error appears in a pop up box:
For point definitions which pass the syntax check, a message box appears indicating the syntax check passed:
The best way to understand how the File-Defined PWL sources work is to look at some examples. This section has five examples, each one with an increasing level of complexity.
You can download this example here: simplis_077_fdpwl_four_pulses_example.sxsch
The example used in the dialog image above defines a pulse train of four pulses. The source definition dialog includes simple data points to define a single pulse with the following parameters:
The dialog for this example is shown below:
Although only one period of the pulse is defined, four pulses are generated because the source file defines the REPEAT_COUNT=3 option on the START_DATA line. Note that the total number of pulses will be the repeat parameter value plus one. Additionally, the Source delay parameter is set to 100us, and all pulses are delayed by this time value. The waveform created by this example is shown below:
You can download this example here: simplis_077_fdpwl_four_pulses_repeat_forever_example.sxsch
The previous example (Four Pulses Example) used the file option to repeat the file definition three times. This example takes the preceding example and builds a periodic source which generates the same four pulses every 1 ms. The source definition has only two points, one super data point and one simple data point:
Notice the first data point references the four_pulses.txt file. This data point is a "super data point" in that the source definition starting at the super data time value, which is zero, will be defined by the four_pulse.txt data file. The source definition is therefore the same as the earlier example for the first four pulses; however, since the Periodic source? checkbox is selected, the source definition will repeat, with the values starting at 1ms, 2ms, 3ms, etc. being the same as the values at 0s. Note that the final data point in this file defines the repeat period of the overall source definition.
This example uses two files with two levels of hierarchy - the top level file has two data points one of which is a super data point and references the file "four_pulses.txt." The referenced file contains all simple data points. The next example shows two levels of file hierarchy with two referenced super data point files.
You can download this example here: simplis_077_fdpwl_ringing_pulses_example.sxsch
This example generates a pulse waveform with ringing on the rising and falling edges, typical of many power converters. To accomplish this, the four_pulses.txt definition is modified from simple data points to have two super data points. Each of the super data points reference a file, and each referenced file describes a damped sinusoidal ringing voltage. The first file, "ringing_pos.txt" generates a positive-going damped sinusoid with an initial amplitude of 10V. The second file, "ringing_neg.txt" defines a negative-going damped sinusoid with a 0V starting amplitude. These super data points replace the 10V and 0V data points in the pulse definition. The three point definition files are stored in the F11 window and the top level file definition is:
The output waveforms for this example are:
The rising and falling edges are shown below:
You can download this example here: simplis_077_fdpwl_scope_waveform_example.zip
This example shows how to define the points for a File-Defined PWL source from a CSV file containing oscilloscope waveform data. Using oscilloscope data requires minor changes to the header of the data file before using the file as a points file for the File-Defined PWL source.
The zip archive contains a test schematic and two data files. The raw_data_points.csv file is direct from the oscilloscope. The edited_scope_data.csv is the definition file used in the simulation of a file defined PWL source, and has been modified using the procedure described next.
To modify raw oscilloscope waveform data for use in the File-Defined PWL source, follow these steps:
After making these changes, the first 7 lines of the file are as follows:
|START_DATA SHIFT_FIRST_TO_ZERO FORMAT=CSV|
The waveform created by this example are shown below:
You can download this example here: simplis_077_fdpwl_truncated_super_data_point_example.sxsch
This example shows how the points defined in a file referenced by super data point are truncated when the parent file defines a data point at a time before the effective end of the super data point.
The dialog for this example is shown below:
The top level file definition is the same as the Ringing Pulses Example except an additional data point is inserted at t=175ns. The source definition of the ringing_pos.txt file has time points from t=0 to t=1us. If points defined in the entire ringing_pos.txt file were included starting at t=100ns, which is the super data point time value, there would be a conflict at the next time point at t=175ns. At 175ns, the top level file defines the source voltage to be 10V, while the ringing_pos.txt file defines a voltage which continues to resonate until the effective time of 1.1us. In these cases, the parent data file point will be used and the rest of the points defined by the super data point file are ignored when the effective source waveform is determined.
Although only two levels of source definition files are used in this example, the data file truncation is carried out throughout the entire source file hierarchy. That is, at each super data point, the next data point in the parent data file will be used if the effective data points brought in by the super data point continue past the time value of the next parent data point.
The waveform created by this example as well as the original ringing pulses example waveform are shown below: