transline_calculation_base.h

Go to the documentation of this file.

/*
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * 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 package.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef TRANSLINE_CALCULATIONS_TRANSLINE_CALCULATION_BASE_H
#define TRANSLINE_CALCULATIONS_TRANSLINE_CALCULATION_BASE_H
 
 
#include <cmath>
#include <optional>
#include <unordered_map>
 
#include <transline_calculations/dielectric_djordjevic_sarkar.h>
 

enum class TRANSLINE_PARAMETERS : int
{
    // The following parameters are accessible from the UI
    UNKNOWN_ID = -1,
    EPSILONR,                 // Dielectric constant
    TAND,                     // Dielectric Loss Tangent
    RHO,                      // Conductivity of conductor
    H,                        // Height of substrate
    H_T,                      // Height of top surface
    T,                        // Height of top conductor
    PHYS_WIDTH,               // Width of trace
    PHYS_DIAM_IN,             // Inner diameter of cable
    PHYS_S,                   // width of gap between line and ground
    PHYS_DIAM_OUT,            // Outer diameter of cable
    PHYS_LEN,                 // Length of cable
    ROUGH,                    // Surface roughness
    MUR,                      // Magnetic permeability of substrate
    MURC,                     // magnetic permeability of conductor
    FREQUENCY,                // Frequency of operation
    STRIPLINE_A,              // Stripline : distance from track to top plane
    TWISTEDPAIR_TWIST,        // Twists per length
    TWISTEDPAIR_EPSILONR_ENV, // Dielectric constant of environment
    Z0,                       // Characteristic impedance
    Z0_E,                     // Even-mode characteristic impedance
    Z0_O,                     // Odd-mode characteristic impedance
    ANG_L,                    // Electrical length in angle
    DUMMY_PRM,
 
    // The following parameters are generated by calculations
    SIGMA,                // Conductivity of the metal
    SKIN_DEPTH,           // Skin depth
    LOSS_DIELECTRIC,      // Loss in dielectric (dB)
    LOSS_CONDUCTOR,       // Loss in conductors (dB)
    CUTOFF_FREQUENCY,     // Cutoff frequency for higher order modes
    EPSILON_EFF,          // Effective dielectric constant
    EPSILON_EFF_EVEN,     // Even mode effective dielectric constant
    EPSILON_EFF_ODD,      // Odd mode effective dielectric constant
    UNIT_PROP_DELAY,      // The unit propagation delay (ps/cm)
    UNIT_PROP_DELAY_ODD,  // The odd mode unit propagation delay (ps/cm)
    UNIT_PROP_DELAY_EVEN, // The even mode unit propagation delay (ps/cm)
    ATTEN_COND,           // The attenuation of the conductor
    ATTEN_COND_EVEN,      // The even mode attenuation of the conductor
    ATTEN_COND_ODD,       // The odd mode attenuation of the conductor
    ATTEN_DILECTRIC,      // The attenuation of the dilectric
    ATTEN_DILECTRIC_EVEN, // The even mode attenuation of the dilectric
    ATTEN_DILECTRIC_ODD,  // The odd mode attenuation of the dilectric
    Z_DIFF,               // The differential impedance
 
    // Common-mode characteristic impedance for a symmetric coupled line, Z_comm = Z0e / 2.
    // The two strips driven at equal potential present Z0e to ground in parallel.  Derived
    // from Pozar, "Microwave Engineering" 4th ed., Sec. 7.6 Eqs. 7.68-7.69.
    Z_COMM,
 
    // Coupling coefficient k_c = (Z0e - Z0o) / (Z0e + Z0o).  Dimensionless, bounded in
    // [0, 1) for physically realisable passive geometries.  Pozar, "Microwave Engineering"
    // 4th ed., Sec. 7.6 Eq. 7.81 (voltage coupling coefficient C).
    COUPLING_K,
 
    // Coplanar waveguide back-metal flag.  A value of 0.0 means ungrounded CPW; a value of 1.0
    // means grounded (CBCPW).  Exposed as a parameter rather than a C++ member so a single
    // COPLANAR class can drive both UI entry points without ad-hoc subclassing.
    CPW_BACKMETAL,
 
    DIELECTRIC_MODEL_SEL, // 0 = CONSTANT, 1 = DJORDJEVIC_SARKAR (double for parameter-map compatibility)
    EPSILONR_SPEC_FREQ,   // Frequency at which EPSILONR and TAND are specified (Hz).
                          // Used only when DIELECTRIC_MODEL_SEL == DJORDJEVIC_SARKAR.
 
    SOLDERMASK_PRESENT,   // 1.0 = mask enabled, 0.0 = disabled.  A zero here must leave the
                          // un-coated Analyse() path bit-identical so every pre-mask regression
                          // test continues to pass without tolerance widening.
    SOLDERMASK_THICKNESS, // Mask layer thickness C, metres.  Zero also produces a bit-identical
                          // un-coated result because tanh(0) = 0 kills the correction Q.
    SOLDERMASK_EPSILONR,  // Mask relative permittivity.  Typical LPI 3.3 - 3.8.
    SOLDERMASK_TAND,      // Mask loss tangent.  Typical LPI 0.025 - 0.035.
    SOLDERMASK_FILLS_GAPS, // CPW / CBCPW only.  1.0 = mask fills the coplanar slots (default),
                           // 0.0 = mask over traces only, slots left air-filled.
 
    EXTRAS_COUNT
};
 

enum class SYNTHESIZE_OPTS
{
    DEFAULT,           // Use the default synthesis options for the calculation
    FIX_WIDTH,         // Fixes the width of a differential pair
    FIX_SPACING,       // Fixes the spacing of a differential pair
    FROM_ZDIFF_ZCOMM   // Read Z_DIFF / Z_COMM as the design target instead of Z0_E / Z0_O.
                       // Translates to (Z0_E, Z0_O) and runs the DEFAULT 2-D solver.  Only
                       // honoured by calculators that can jointly optimise both modes.
};
 

enum class DIELECTRIC_MODEL : int
{
    CONSTANT,          // Classic behaviour, epsR and tan delta are frequency-independent.
    DJORDJEVIC_SARKAR, // Causal wideband Debye.  See Djordjevic et al. 2001 IEEE TEMC 43(4).
};
 

enum class TRANSLINE_STATUS
{
    OK,
    WARNING,
    TS_ERROR        // ERROR name is colliding with a define on Windows
};
 

class TRANSLINE_CALCULATION_BASE
{
public:
    TRANSLINE_CALCULATION_BASE( std::initializer_list<TRANSLINE_PARAMETERS> aParameters )
    {
        InitProperties( aParameters );
    }
 
    virtual ~TRANSLINE_CALCULATION_BASE() {}

    void SetParameter( const TRANSLINE_PARAMETERS aParam, const double aValue ) { m_parameters.at( aParam ) = aValue; }

    double GetParameter( const TRANSLINE_PARAMETERS aParam ) const { return m_parameters.at( aParam ); }

    double& GetParameterRef( const TRANSLINE_PARAMETERS aParam ) { return m_parameters[aParam]; }

    std::unordered_map<TRANSLINE_PARAMETERS, std::pair<double, TRANSLINE_STATUS>>& GetAnalysisResults();

    std::unordered_map<TRANSLINE_PARAMETERS, std::pair<double, TRANSLINE_STATUS>>& GetSynthesisResults();

    virtual void Analyse() = 0;

    virtual bool Synthesize( SYNTHESIZE_OPTS aOpts ) = 0;

    virtual void SetSynthesizeTarget( TRANSLINE_PARAMETERS aTarget ) { m_synthesizeTarget = aTarget; }

    TRANSLINE_PARAMETERS GetSynthesizeTarget() const { return m_synthesizeTarget; }

    void UpdateDielectricModel();

    double GetDispersedEpsilonR( double aF ) const;

    double GetDispersedTanDelta( double aF ) const;

    virtual double GetSoldermaskDeltaQ( double /*aWOverH*/, double /*aCOverH*/ ) const
    {
        return 0.0;
    }

    std::pair<double, double> ApplySoldermaskCorrection( double aEpsEffUncoated,
                                                         double aTanDeltaSubstrate,
                                                         double aEpsRSubstrate,
                                                         double aWOverH,
                                                         double aF ) const;

    static double WanHoorfarQ2( double aU, double aHBarTop );
 
protected:
    void InitProperties( const std::initializer_list<TRANSLINE_PARAMETERS>& aParams );

    virtual void SetAnalysisResults() = 0;

    virtual void SetSynthesisResults() = 0;

    void SetAnalysisResult( TRANSLINE_PARAMETERS aParam, const double aValue,
                            const TRANSLINE_STATUS aStatus = TRANSLINE_STATUS::OK );

    void SetSynthesisResult( TRANSLINE_PARAMETERS aParam, const double aValue,
                             const TRANSLINE_STATUS aStatus = TRANSLINE_STATUS::OK );

    bool MinimiseZ0Error1D( TRANSLINE_PARAMETERS aOptimise, TRANSLINE_PARAMETERS aMeasure,
                            bool aRecalculateLength = false );

    bool MinimiseZ0Error2D( TRANSLINE_PARAMETERS aParam1, TRANSLINE_PARAMETERS aParam2 );

    double SkinDepth() const;

    static double UnitPropagationDelay( double aEpsilonEff );

    static std::pair<double, double> EllipticIntegral( double arg );

    static double coth( const double x ) { return ( std::exp( 2.0 * x ) + 1.0 ) / ( std::exp( 2.0 * x ) - 1.0 ); }

    static double sech( const double x ) { return 2.0 / ( std::exp( x ) + std::exp( -x ) ); }

    std::unordered_map<TRANSLINE_PARAMETERS, double> m_parameters;

    std::unordered_map<TRANSLINE_PARAMETERS, std::pair<double, TRANSLINE_STATUS>> m_analysisStatus;

    std::unordered_map<TRANSLINE_PARAMETERS, std::pair<double, TRANSLINE_STATUS>> m_synthesisStatus;

    static constexpr double m_maxError{ 0.000001 };

    TRANSLINE_PARAMETERS m_synthesizeTarget{ TRANSLINE_PARAMETERS::UNKNOWN_ID };

    std::optional<DIELECTRIC_DJORDJEVIC_SARKAR> m_dsModel;
};
 
#endif //TRANSLINE_CALCULATIONS_TRANSLINE_CALCULATION_BASE_H