# SLiCAPrst.py

SLiCAP formatter for generating snippets that can be stored as RST files and included in other RST files.

class RSTformatter

  Formatter. The methods return ReStructuredText snippets.

  Example:

      >>> import SLiCAP as sl
      >>> sl.initProject("formatter")
      >>> rst = sl.RSTformatter()   # Creates an instance of a ReStructuredText formatter

  coeffsTransfer(transferCoeffs, label='', caption='')

    Creates a tablestable that displays the numerator and denominator coefficients of a rational expression. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - stepVars (list) – List with step variables (str, sympy.Symbol).

      - stepArray (List) – List with lists with step values for each step variable

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

    Example:

        >>> import SLiCAP as sl
        >>> import sympy as sp
        >>>
        >>> rst  = sl.RSTformatter()
        >>> expr = sp.sympify("A_0*(1+s*b_1)/(((1+s*a_1))*((1+s*a_2)))")
        >>> tr_coeffs = sl.coeffsTransfer(expr)
        >>> rst.coeffsTransfer(tr_coeffs,
                               label="tab-coeffs",
                               caption = "numerator and denominator " +
                               "coefficients").save("coeffs")

  dcvarContribs(resultObject, label='', caption='')

    Creates a table with results of dcvar analysis stored in resultObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - resultObject (SLiCAP.SLiCAPinstruction.instruction) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption(s).

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  dictTable(dct, head=None, label='', caption='')

    Creates a table from a dictionary; optionally with a header. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - dct – Dictionary with key-value pairs.

      - head (list) – List with names for the key column and the value column, respectively. List items will be converted to string.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  elementData(circuitObject, label='', caption='')

    Creates a table with data of expanded netlist elements of circuitObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - circuitObject (SLiCAP.SLiCAPprotos.circuit) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  eqn(LHS, RHS, units='', label='', multiline=False)

    Creates a displayed (numbered) equation.

    Parameters:

      - LHS (str, sympy.Symbol, sympy.Expr) – Left hand side of the equation.

      - RHS (sympy.Symbol, sympy.Expr) – Right hand side of the equation.

      - units (str) – Units

      - label (str) – Reference label for the table. Defaults to an empty string.

      - multiline (int, Bool) – n breaks the equation over multiple lines with n sums or products per line

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

    Example:

        >>> import SLiCAP as sl
        >>> import sympy as sp
        >>>
        >>> rst = sl.RSTformatter()
        >>> lhs = sp.sympify("e^(1j*pi)")
        >>> rhs = sp.N(-1)
        >>> rst.eqn(lhs, rhs, label="nice_eqn").save("nice_eqn")

  eqnInline(LHS, RHS, units='', name=None)

    Creates in inline equation.

    Parameters:

      - LHS (sympy.Expr, str) – Left hand side of the equation

      - RHS (sympy.Expr) – Right hand side of the equation

      - units (str) – Units

      - name (str:) – Name of the variable for RST substitution.

    Returns:

      SLiCAP Snippet object with save variable append mode

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  expr(expr, units='', name=None)

    Creates in inline expression.

    Parameters:

      - expr – Expression

      - units (str) – Units

      - name (str:) – Name of the variable for RST substitution.

    Returns:

      SLiCAP Snippet object with save variable append mode

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  file(fileName, lineRange=None, firstNumber=None)

    Creates a n RST .. literalinclude:: command for literally displaying a file.

    Parameters:

      - fileName (str) – Name of the file. Path is absolute or relative to the project directory

      - lineRange (str) – range of lines to be included

      - firstNumber (str) – start number of the displayed line numbers

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  matrixEqn(Iv, M, Dv, label='')

    Creates a displayed matrix equation without evaluating it.

    Parameters:

      - Iv (sympy.Matrix) – Left hand side of the equation: vector with independent variables

      - M (sympy.Matrix) – Right hand side of the equation: matrix

      - Dv (sympy.Matrix) – Righthand side of the equation: vector with dependent variables

      - label (str) – Reference label for the table. Defaults to an empty string.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  nestedLists(headerList, linesList, unitpos=None, caption='', label='')

    Creates and returns an RST table snippet that can be included in a ReStructuredText document. Each list is converted into a table row and must have equal lengths. There can be one column with units.

    A label can be given as reference and a caption can be added.

    Parameters:

      - name (str) – Table caption, defauls to ‘’

      - headerList (list with strings) – List with column headers.

      - linesList (list) – List with lists of table data for each table row

      - label (str) – Table reference label

    Returns:

      RST snippet to be included in a ReStructuredText document

    Return type:

      str

  netlist(netlistFile, lineRange=None, firstNumber=None)

    Creates a LaTeX input{} or an RST ‘.. literalinclude:: ‘ command for including a netlist file.

    Parameters:

      - netlistFile (str) – Name of the netlist file relative to the project circuit directory

      - lineRange (str) – range of lines to be included

      - firstNumber (str) – start number of the displayed line numbers

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

    Example:

        >>> import SLiCAP as sl
        >>> rst = sl.RSTformatter() # Creates a ReStructuredText formatter
        >>> rst.netlist("myFirstRCnetwork.cir").save("netlist")

    This will save a file netlist.rst in the sl.ini.rst_snippets folder with the following contents:

        .. literalinclude:: <full path to myFirstRCnetwork.cir>
            :linenos:

  noiseContribs(resultObject, label='', caption='')

    Creates a table with results of noise analysis stored in resultObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - resultObject (SLiCAP.SLiCAPinstruction.instruction) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption(s).

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  parDefs(circuitObject, label='', caption='')

    Creates a table with parameter definitions of circuitObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - circuitObject (SLiCAP.SLiCAPprotos.circuit) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  params(circuitObject, label='', caption='')

    Creates a table with undefined parameters of circuitObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - circuitObject (SLiCAP.SLiCAPprotos.circuit) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  pz(resultObject, label='', caption='')

    Creates a table or tables with results of pole/zero analysis stored in resultObject. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - resultObject (SLiCAP.SLiCAPinstruction.instruction) – SLiCAP circuit object that comprises the circuit data to be listed.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Text that will used as table caption(s).

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  specs(specs, specType, label='', caption='')

    Creates a table with specifications of type specType. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - specs (list) – List with SLiCAP.SLiCAPdesignData.specItem objects.

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet

  stepArray(stepVars, stepArray, label='', caption='')

    Creates a table with step array values. If no label AND no caption are given this method returns a LaTeX tabular snippet. Else it returns a table snippet.

    Parameters:

      - stepVars (list) – List with step variables (str, sympy.Symbol).

      - stepArray (List) – List with lists with step values for each step variable

      - label (str) – Reference label for the table. Defaults to an empty string.

      - caption (str) – Table caption.

    Returns:

      SLiCAP Snippet object

    Return type:

      SLiCAP.SLiCAPprotos.Snippet