NAME

PDL::IO::Touchstone - Read and manipulate Touchstone .s2p (and .sNp) files.

DESCRIPTION

A simple interface for reading and writing RF Touchstone files (also known as ".sNp" files). Touchstone files contain complex-valued RF sample data for a device or RF component with some number of ports. The data is (typically) measured by a vector network analyzer under stringent test conditions.

The resulting files are usually provided by manufacturers so RF design engineers can estimate signal behavior at various frequencies in their circuit designs. Examples of RF components include capacitors, inductors, resistors, filters, power splitters, etc.

SYNOPSIS

        use PDL::IO::Touchstone;

        # Read input matrix:
        ($f, $m, $param_type, $z0, $comments, $fmt, $funit, $orig_f_unit) =
                rsnp('input-file.s2p', { units => 'MHz' }); 


        # Write output file:
        wsnp('output-file.s2p',
                $f, $m, $param_type, $z0, $comments, $fmt, $from_hz, $to_hz);

You can reproduce the same output file from an input as follows:

        @data = rsnp('input-file.s2p');
        wsnp('output-file.s2p', @data);

You may convert between output formats or frequency scale by changing the $fmt and $to_hz fields when writing:

        @data = rsnp('input-file.s2p');
        $data[5] = 'DB'; # $fmt
        $data[7] = 'MHz' # $to_hz in wsnp() or $orig_f_unit from rsnp().
        wsnp('output-file.s2p', @data);

Note that you may change neither $param_type nor $z0 unless you have done your own matrix transform from one parameter type (or impedance) to another. This is because while wsnp knows how to convert between RA, MA, and DB formats, it does not manipulate the matrix to convert between parameter types (or impedances). Use the P_to_Q() functions below to transform between matrix types.

IO Functions

`rsnp($filename, $options)` - Read touchstone file

Arguments:

$filename - the file to read
$options - A hashref of options.

Currently only 'units' is supported, which may specify one of Hz, KHz, MHz, GHz, or THz. The resulting $f vector will be scaled to the frequency format you specify. If you do not specify a format then $f will be scaled to Hz such that a value of 1e6 in the $f vector is equal to 1 MHz.

Return values

The first set of parameters ($f, $m, $param_type, $z0) are required to properly utilize the data loaded by rsnp():

$f - A (M) vector piddle of input frequencies where M is the number of frequencies.
$m - A (N,N,M) piddle of X-parameter matrices where N is the number of ports and M is the number of frequencies.

These matrixes have been converted from their 2-part RI/MA/DB input format and are ready to perform computation. Matrix values (S11, etc) use PDL's native complex values.
$param_type - one of S, Y, Z, H, G, T, or A that indicates the matrix parameter type.

Note that T and A are not officially supported Touchstone formats, but you can still load them with this module (but it is up to you to know how to use them).
$z0 - The characteristic impedance reference used to collect the measurements.

The remaining parameters ($comments, $fmt, $funit) are useful only if you wish to re-create the original file format by calling wsnp():

$comments - An ARRAY-ref of full-line comments provided at the top of the input file.
$fmt - The format of the input file, one of:
- RI - Real/imaginary format
- MA - Magnitude/angle format
- DB - dB/angle format
$funit - The frequency unit used by the $f vector

The $funit value is typically 'Hz' unless you overrode the frequency scaling unit with $options in your call to rsnp(). If you specified a unit the $funit will use that unit so a call to wsnp() will re-create the original touchstone file.
$orig_funit - The frequency unit used by the original input file.

`wsnp($filename, $f, $m, $param_type, $z0, $comments, $fmt, $from_hz, $to_hz)`

Arguments

Except for $filename (the output file), the arguments to wsnp() are the same as those returned by rsnp().

When writing it is up to you to maintain consistency between the output format and the data being represented. Except for complex value representation in $fmt and frequency scale in $f, this PDL::IO::Touchstone module will not make any mathematical transform on the matrix data.

Changing $to_hz will modify the frequency format in the resultant Touchstone file, but the represented data will remain correct because Touchstone knows how to scale frequencies.

Roughly speaking this should create an identical file to the input:

        wsnp('output.s2p', rsnp('input.s2p'));

However, there are a few output differences that may occur:

Floating point rounding during complex format conversion
Same-line "suffix comments" are stripped
The order of comments and the "# format" line may be changed. wsnp() will write comments before the "# format" line.
Whitespace may differ in the output. Touchstone specifies any whitespace as a field delimiter and this module uses tabs as delimiters when writing output data.

`wsnp_fh($fh, $f, $m, $param_type, $z0, $comments, $fmt, $from_hz, $to_hz)`

Same as wsnp() except that it takes a file handle instead of a filename. Internally wsnp() uses wsnp_fh() and wsnp_fh() can be useful for building MDF files, however MDF files are much more complicated and outside of this module's scope. Consult the "SEE ALSO" section for more about MDFs and optimizing circuits.

S-Parameter Conversion Functions

Each matrix below is in the (N,N,M) format where N is the number of ports and M is the number of frequencies.
The value of $z0 in the conversion functions may be complex-valued and is represente as either:

- A perl scalar value: all ports have same impedance

- A 0-dim pdl like pdl( 5+2*i() ): all ports have same impedance

- A 1-dim single-element pdl like pdl( [5+2*i()] ): all ports have same impedance

- A 1-dim pdl representing the charectaristic impedance at each port: ports may have different impedances

`$Y = s_to_y($S, $z0)`: Convert S-paramters to Y-parameters.

$S: The S-paramter matrix
$z0: Charectaristic impedance (see above).
$Y: The resultant Y-paramter matrix

`$S = y_to_s($Y, $z0)`: Convert Y-paramters to S-parameters.

$Y: The Y-paramter matrix
$z0: Charectaristic impedance (see above).
$S: The resultant S-paramter matrix

`$Z = s_to_z($S, $z0)`: Convert S-paramters to Z-parameters.

$S: The S-paramter matrix
$z0: Charectaristic impedance (see above).
$Z: The resultant Z-paramter matrix

`$S = z_to_s($Z, $z0)`: Convert Z-paramters to S-parameters.

$Z: The Z-paramter matrix
$z0: Charectaristic impedance (see above).
$S: The resultant S-paramter matrix

`$ABCD = s_to_abcd($S, $z0)`: Convert S-paramters to ABCD-parameters.

$S: The S-paramter matrix
$z0: Charectaristic impedance (see above).
$ABCD: The resultant ABCD-paramter matrix

`$S = abcd_to_s($ABCD, $z0)`: Convert ABCD-paramters to S-parameters.

$ABCD: The ABCD-paramter matrix
$z0: Charectaristic impedance (see above).
$S: The resultant S-paramter matrix

AUTHOR

Originally written at eWheeler, Inc. dba Linux Global Eric Wheeler to transform .s2p files and build MDF files to optimize with Microwave Office for amplifer impedance matches.

COPYRIGHT

This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this module. If not, see <http://www.gnu.org/licenses/>.

To install PDL::IO::Touchstone, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PDL::IO::Touchstone

CPAN shell

perl -MCPAN -e shell
install PDL::IO::Touchstone

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SYNOPSIS

IO Functions

rsnp($filename, $options) - Read touchstone file

Arguments:

Return values

wsnp($filename, $f, $m, $param_type, $z0, $comments, $fmt, $from_hz, $to_hz)

Arguments

wsnp_fh($fh, $f, $m, $param_type, $z0, $comments, $fmt, $from_hz, $to_hz)

S-Parameter Conversion Functions

$Y = s_to_y($S, $z0): Convert S-paramters to Y-parameters.

$S = y_to_s($Y, $z0): Convert Y-paramters to S-parameters.

$Z = s_to_z($S, $z0): Convert S-paramters to Z-parameters.

$S = z_to_s($Z, $z0): Convert Z-paramters to S-parameters.

$ABCD = s_to_abcd($S, $z0): Convert S-paramters to ABCD-parameters.

$S = abcd_to_s($ABCD, $z0): Convert ABCD-paramters to S-parameters.

SEE ALSO