File-Defined Piecewise Linear Source (FDPWL)

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: Voltage Sources > PWL Voltage Source (File Defined)
Current Sources > PWL Current Source (File Defined)
Symbol Library: sources.sxslb
Model File: none, the FDPWL is a SIMPLIS primitive model
Symbol:
Multiple Selections: Multiple devices can be selected and edited simultaneously.

Editing the File-Defined PWL Source

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.

Label Units Description
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.

Filename and Location

A referenced data file can be an embedded (in-the-deck) data file defined through the .FILE/ .ENDF construct, or it can be a real physical file according to the operating system. The dialog allows you to save your file to the F11 window with the contents inserted into the .FILE and .END statements. Files saved to the F11 window are embedded, or in-the-deck files. The selected radio button Disk or F11 window determines where the file is saved when the dialog is closed. It is therefore possible to have files with the same filename on disk and in the F11 window.
CAUTION:
If you have a file saved in the F11 window with the same name as a file saved to disk, the simulation will unconditionally use the file definition saved in the F11 window. This is true independent of the state of the File location radio button.

File options

Each data file has three options:

Label Description
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.

Filename Restrictions

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.

File Syntax

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.

File Content

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.

The first non-comment line must start with the keyword START_DATA. This line must be present in each data file and must precede the first data point in the file. The file options are entered on the START_DATA line in any order after the START_DATA keyword. REPEAT_COUNT, FORMAT=CSV, and SHIFT_FIRST_TO_ZERO are optional parameters and are not required. If all three optional parameters were omitted, REPEAT_COUNT is set to 0, the file's time values will not be shifted to zero and the file format is expected to be in tab delimited format. The syntax of the optional parameters are:
  • REPEAT_COUNT=R
  • FORMAT=CSV
  • SHIFT_FIRST_TO_ZERO
where R is a non-negative integer from 0 to 1000 to stand for repeat count of the data. CSV is literally the three-character string "CSV" to indicate the data file is stored in the comma-separated format. In this case, each line is made up of fields separated by commas and follow the rule for the comma-separated values standard. The optional keyword SHIFT_FIRST_TO_ZERO is a literal keyword with no value. If it is present, all data points in the file will be shifted by the same amount so that the first data point appears to occur at t=0.

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.

Each data point is defined by a time value, followed by an amplitude value. For example, the following data file named "four_pulses" has 5 data points, defined with time values of 0s, 100ns, 10us, 10.1us, and 100us, respectively.
START_DATA REPEAT_COUNT=3
0 0
100n 10
10u 10
10.1u 0
100u 0

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 file contains at least two data points and at most 100001 data points.
  • The time value of the first data point must be equal to 0.0 unless the SHIFT_FIRST_TO_ZERO keyword is present on the START_DATA line.
  • Except for the first data point, the time value of each data point must be no less than the value of the previous data point.
  • The time value of the last data point must be larger than the time value of the first data point.

Simple and Super Data Points

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:

START_DATA REPEAT_COUNT=3
0 0
100n file="ringing_pos.txt"
10u 10
10.1u file="ringing_neg.txt"
100u 0

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.

Super Data Point Expansion

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.

Checking File Syntax

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:

Note: This function is computationally intensive and may take several seconds to complete.

For point definitions which pass the syntax check, a message box appears indicating the syntax check passed:

Examples

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.

Four Pulses Example

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:

  • 100ns rise and fall times.
  • 9.9us "high" time duration.
  • 10V "high" amplitude.
  • 0V "low" amplitude.
  • 100us final data point.

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:

Periodic Source Example

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.

Ringing Pulses Example

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:

Oscilloscope Waveform Data Example

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:

  1. Open the raw data file in a text editor.
  2. Typical data files have information about the oscilloscope waveform on the first few lines. The first 7 lines of a typical waveform file are shown below in table form - each file line is parsed into table columns on the comma character.
    LECROYWR64MXi 11588 Waveform  
    Segments 1 SegmentSize 20002
    Segment TrigTime TimeSinceSegment1  
    #1 06-Dec-2010 17:50:52 0  
    Time Ampl    
    -4.0005185e-007 0.000307188    
    -3.9995185e-007 -0.159687    
  3. Insert an asterisk (*) character at the beginning of each information line, in this example the first five lines are information and need to be commented out.
  4. Insert a START_DATA line after the last commented out information line and before the first waveform data point. Because this file has time points which have negative time values, the SHIFT_FIRST_TO_ZERO keyword is required and since the file is in CSV format, the FORMAT=CSV keyword is also required. The text of the START_DATA line is START_DATA SHIFT_FIRST_TO_ZERO FORMAT=CSV

After making these changes, the first 7 lines of the file are as follows:

*LECROYWR64MXi 11588 Waveform  
*Segments 1 SegmentSize 20002
*Segment TrigTime TimeSinceSegment1  
*#1 06-Dec-2010 17:50:52 0  
*Time Ampl    
START_DATA SHIFT_FIRST_TO_ZERO FORMAT=CSV
-4.0005185e-007 0.000307188    

The waveform created by this example are shown below:

Truncated Super Data Point Example

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: