(* $Id: RFCommon.m,v 1.5.2.2 2003/02/14 07:00:42 hennig Exp $ *)

(* {{{ Mathematica meta tags *)

(* :Title: Analog Insydes RF Common *)

(* :Authors: Dr.-Ing. Eckhard Hennig, eckhard@kaninkolo.de *)

(* :Summary: This module contains common functions and definitions for
  the AnalogInsydes`RF` context. *)

(* :Context: AnalogInsydes`RF`RFCommon`  *)

(* :Package Version: $Revision: 1.5.2.2 $ *)

(* :Mathematica Version: > 3.0 *)

(* :Copyright: Copyright (C) 2001-2003 by Eckhard Hennig

  This program 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 2
  of the License, or (at your option) any later version.

  This program 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 program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*)

(* :History:
 * $Log: RFCommon.m,v $
 * Revision 1.5.2.2  2003/02/14 07:00:42  hennig
 * + Special treatment of symbol ShowHeader.
 *
 * Revision 1.5.2.1  2003/01/29 12:31:35  hennig
 * + GPL.
 *)

(* :Keywords: *)

(* :Sources: *)

(* :Warning: *)

(* :Limitation: *)

(* :Discussion: *)

(* }}} *)

(* {{{ Version check *)

(******************************************************************************)
(* Analog Insydes RF Common Functions.                                        *)
(******************************************************************************)

If[ $VersionNumber < 3.0,
  Print["This program requires Mathematica Version 3.0 or higher."];
  Abort[]
];

(* }}} *)

BeginPackage[ "AnalogInsydes`RF`RFCommon`",
              "AnalogInsydes`Master`",
              "AnalogInsydes`Common`",
              "AnalogInsydes`Miscellaneous`" ]

(* {{{ Protection declarations, exported; Unprotect *)

(* The symbol ShowHeader may appear in custom versions of Analog Insydes,
  therefore we must avoid potential collisions. *)
`Private`$ShowHeaderFlag = (Names["ShowHeader"] === {})

(******************************************************************************)
(* Protection for exported symbols                                            *)
(******************************************************************************)

`Private`$ExportedProtectedSymbols = {
  NoiseFigure,
  NoiseResistance,
  PositiveArcTan,
  ReferenceImpedance,
  ReflectionCoefficient,
  ReIm,
  SourceReflection,
  VSWR
}
If[`Private`$ShowHeaderFlag,
  AppendTo[`Private`$ExportedProtectedSymbols, ShowHeader] ]

(******************************************************************************)
(* Unprotection for exported symbols                                          *)
(******************************************************************************)

Unprotect @@ `Private`$ExportedProtectedSymbols;

(* }}} *)

(* {{{ Usage declarations *)

(******************************************************************************)
(* Usage declarations                                                         *)
(******************************************************************************)

NoiseFigure::usage = "NoiseFigure is a symbol used to denote noise figure
traces in s-parameter sets."

NoiseResistance::usage = "NoiseResistance is a symbol used to denote normalized
effective noise resistance traces in noise sections in s-parameter sets."

PositiveArcTan::usage = "PositiveArcTan[x, y] computes ArcTan[x, y] for real
numbers x and y. The result is mapped to the positive real interval [0..2 Pi]."

ReferenceImpedance::usage = "ReferenceImpedance is an option for several Analog
Insydes RF functions, specifying the value of the reference impedance for
computing reflection coefficients. The reference impedance must be a positive
real number."

ReflectionCoefficient::usage = "ReflectionCoefficient[Z, Zref] computes the
reflection coefficient associated with the impedance ratio Z/Zref, where Zref
denotes the reference impedance."

ReIm::usage = "ReIm[z] returns the real and imaginary part of the complex number
z in the form {Re z, Im z}."

SourceReflection::usage = "SourceReflection is a symbol used to denote source
reflection coefficient traces in noise sections of s-parameter sets."

If[ `Private`$ShowHeaderFlag,
  ShowHeader::usage = "ShowHeader is an option for ReadTouchstone, specifying
whether to display Touchstone file headers."
]

VSWR::usage = "VSWR[r] returns the voltage standing wave ratio associated with
the reflection coefficient r."

(* }}} *)

(* {{{ Error messages *)

(******************************************************************************)
(* Error messages                                                             *)
(******************************************************************************)

(* }}} *)


Begin["`Private`"]

(* {{{ VersionID *)

(******************************************************************************)
(* VersionID                                                                  *)
(******************************************************************************)

$VersionId = "$Id: RFCommon.m,v 1.5.2.2 2003/02/14 07:00:42 hennig Exp $"

(* }}} *)

(* {{{ Option checking rules *)

Unprotect[Ports];
Ports /:
CheckOption[Ports, value_] :=
  If[ Head[value] =!= Integer || value <= 0,
    Message[Option::posint, Ports, value, $Failed];
    $Failed,
    value ];
Protect[Ports]

ReferenceImpedance /:
CheckOption[ReferenceImpedance, value_] :=
  If[ !Positive[N[value]],
    Message[Option::posreal, ReferenceImpedance, value, 50.0];
    50.0,
    N[value] ]

If[ $ShowHeaderFlag,
  ShowHeader /:
  CheckOption[ShowHeader, value_] :=
    If[ NotBooleanQ[value],
      Message[Option::boolval, ShowHeader, value, False];
      False,
      value ]
]

(* }}} *)

(* {{{ Global constants *)

(* }}} *)

(* {{{ ReflectionCoefficient, VSWR *)

(******************************************************************************)
(* ReflectionCoefficient calculates the reflection coefficient of the         *)
(* impedance Z w.r.t. the reference impedance Z0.                             *)
(******************************************************************************)

ReflectionCoefficient[Z_, Z0_:1] := (Z - Z0)/(Z + Z0)


(******************************************************************************)
(* VSWR computes the voltage standing wave ratio associated with the          *)
(* reflection coefficient r.                                                  *)
(******************************************************************************)

VSWR[r_] := With[{ra = Abs[r]}, (1 + ra)/(1 - ra)]

(* }}} *)

(* {{{ ReIm, PositiveArcTan *)

(******************************************************************************)
(* ReIm returns the real and imaginary parts of a complex number.             *)
(******************************************************************************)

ReIm[x_] := N @ {Re[x], Im[x]}


(******************************************************************************)
(* PositiveArcTan maps the return value of ArcTan to the interval [0..2 Pi].  *)
(******************************************************************************)

PositiveArcTan[x_Real, y_Real] :=
  With[ {a = ArcTan[x, y]},
    If[a < 0, a + 2.0*Pi, a] ] 

(* }}} *)

End[]

(* {{{ Protection of exported symbols *)

Protect @@ `Private`$ExportedProtectedSymbols;
Remove[`Private`$ExportedProtectedSymbols];

(* }}} *)

EndPackage[]

(*! Local Variables *)
(* local Variables: *)
(* fill-column: 79 *)
(* comment-column: 20 *)
(* End: *)
