User Manual

pyfda screenshot

Fig. 1 Screenshot of pyfda

Fig. 1 shows the main pyfda screen with three subwindows that can be resized with the handles (red dots).

The tabs on the left-hand side access widgets to enter and view various specification and parameters for the filter / system to be designed resp. analyzed.

**Subwindow for Input Widgets**

The subwidgets on the right-hand side allow for graphical analyses of the system.

**Subwindow for Plotting Widgets**

Some documentation treats general filter design and fixpoint arithmetics stuff.

**General Documentation**

Logger Subwindow

The logging window in the lower part of the plotting window can be resized or completely closed. Its content can be selected, copied or cleared with a right mouse button context menu.

Customization

You can customize pyfda behaviour in some configuration files:

pyfda.conf

A copy of pyfda/pyfda.conf is created in <USER_HOME>/.pyfda/pyfda.conf where it can be edited by the user to choose which widgets and filters will be included. Fixpoint widgets can be assigned to filter designs and one or more user directories can be defined if you want to develop and integrate your own widgets (it’s not so hard!):

# This file configures filters and plotting routines for pyFDA
# ------------------------------------------------------------------
# - Encoding should be either UTF-8 without BOM or standard ASCII
# - All lines starting with # or ; are regarded as comments,
#   inline comments are not allowed
# - [Section] starts a new section
# - Options and values are separated by a ":" or "=" (e.g. dir1 : /home),
#   values are optional
# - Values are "sanitized" by removing [], ' and "
# - Values are split at commas, semicolons or CRs into a list of values
# - Values starting with a { are converted to a dict
# - "Interpolation" i.e. referencing values within the config file via e.g. ${dir1}
#   or ${Common:user_dir1} can be used


###################
[Common]
###################
# Stop pyfda when the parsed conf file has a lower version than required

version = 4

#------------------------------------------------------------------------------
# Define variables than can be referenced in other sections by preceding the
# section name, e.g. fir_df1 = ${Common:FIR} is resolved to 
# fir_df1 = [Equiripple, Firwin, Manual, MA]
#------------------------------------------------------------------------------

# 
IIR = [Bessel, Butter, Cheby1, Cheby2, Ellip]
FIR = [Equiripple, Firwin, Manual, MA]

#------------------------------------------------------------------------------
# Add paths for special tools (optional):
#------------------------------------------------------------------------------
# yosys = "D:\Programme\yosys-win32-mxebin-0.9\yosys.exe"


#------------------------------------------------------------------------------
# Add user directory(s) to sys.path (optional):
#------------------------------------------------------------------------------
#
# Specify relative or absolute path(s) to one or more user directories. These
# directories are searched for the following subdirectories which must be named 
# like the corresponding pyfda directories:
#
# input_widgets    # widgets for specifying filter parameters
# plot_widgets     # widgets for plotting filter properties
# filter_widgets   # widgets for controlling filter design algorithms
# fixpoint_widgets # widgets for specifying fixpoint filters
#
# These subdirectories need to contain an (usually empty) 
# __init__.py file to be recognized as python modules.
#
# When a specified directory cannot be found, only a warning is issued.
#------------------------------------------------------------------------------
# Uncomment and specify your user directory (optional):
#
#user_dirs = "D:\Daten\design\python\git\pyfda\pyfda\widget_templates",
#             "/home/muenker/Daten/design/python/user_pyfda"
             
###############################################################################
# The following sections define which classes will be imported by specifying 
# the module names (= file names without .py suffix). The actual class names are
# obtained from a module level attribute "classes" in each module which can be a:
#
# - String, e.g. classes = "MyClassName"
# - List, e.g.   classes = ["MyClassName1", "MyClassName2"]
# - Dict, e.g.   classes = {"MyClassName1":"DisplayName1", "MyClassName2":"DisplayName2"}
#
# When no display name is given, the class name is used for tab labels, combo boxes etc.
#
# Modules are searched in all directories defined in sys.path and the user dir(s)
# and their subdirectories containing __init__.py files (subpackages) with the 
# names listed above ("input_widgets" etc.)
#
# In addition to specifying only the module name, options can be passed as key-
# value combinations. Unknown options just raise a warning.


########################
[Input Widgets]
########################
# Try to import from the following input widget modules (files) from sys.path
# and subdirectories / subpackages named "input_widgets".

input_specs
input_coeffs
input_pz
input_info
input_fixpoint_specs

########################
[Plot Widgets]
########################
# Try to import from the following plot widget modules (files) from sys.path
# and subdirectories / subpackages named "plot_widgets".

plot_hf : {'opt1':'aaa', 'opt2':'bbb'}
plot_phi
plot_tau_g
plot_pz
plot_impz
plot_3d
# myplot # this could be the name of your user module

########################
[Filter Widgets]
########################
# The specified filter design modules (files) are searched for in sys.path 
# and in subdirectories / subpackages named "filter_widgets".
#
# The optional 'fix' argument defines one or more fixpoint implementations for
# the filter design. Unknown fixpoint implementations only raise a warning.
# In the "Fixpoint Widgets" section, fixpoint implementation can be assigned
# to filter designs as well.

# --- IIR ---
# super_filter : {'fix':['iir_cascade', 'iir_df1']}
# bessel : {'fix':['iir_cascade', 'iir_df1']}
bessel
butter
# cheby1 : "yet another option"
cheby1
# cheby2 : {'fix':'iir_special'}
cheby2
ellip
# ellip_zero # too specialized for general usage

# --- FIR ---
equiripple
firwin 
ma
# delay # still buggy
# savitzky_golay # not implemented yet

# --- Manual (both FIR and IIR) ---
manual


########################
[Fixpoint Widgets]
########################
# Try to import from the following fixpoint widget modules (files) from sys.path 
# and subdirectories / subpackages named "fixpoint_widgets".
#
# Value is a filter design or a list of filter designs for which the fixpoint 
# widget can be used.

fir_df.fir_df_pyfixp_ui = ${Common:FIR}
iir_df1.iir_df1_pyfixp_ui = ${Common:IIR}
# fir_df.fir_df_nmigen_ui = ${Common:FIR}
# fx_delay = ['Equiripple', 'Delay'] # need to fix fx_delay and Delay modules

pyfda_log.conf

A copy of pyfda/pyfda_log.conf is created in <USER_HOME>/.pyfda/pyfda_log.conf where it can be edited to control logging behaviour:

[loggers]
# List of loggers:
# - root logger has to be present
# - section name is "logger_" + name specified in the keys below. The logger
#   name is derived automatically in the files-to-be-logged from their
#  __name__ attribute (i.e. the file name without suffix)
# When a file doesn't exist (e.g. no_existo.py)
#
keys=root, pyfdax, pyfda_class, filter_factory, filterbroker,
     pyfda_lib, pyfda_sig_lib, pyfda_fix_lib, pyfda_qt_lib, pyfda_io_lib,
     pyfda_fft_windows_lib, tree_builder, csv_option_box,
     amplitude_specs, freq_specs, freq_units, input_coeffs, input_coeffs_ui,
     input_fixpoint_specs, input_info, input_pz, input_pz_ui, input_specs,
     input_tab_widgets, select_filter, target_specs,
     bessel, equiripple, firwin,
     fir_df_pyfixp, fir_df_pyfixp_ui, iir_df1_pyfixp, iir_df1_pyfixp_ui,
     mpl_widget, plot_3d, plot_fft_win, plot_hf, plot_impz, plot_impz_ui,
     plot_phi, plot_pz, plot_tab_widgets, plot_tau_g,
     plot_tran_stim, plot_tran_stim_ui, tran_io, tran_io_ui,
     no_existo

[handlers]
# List of handlers
keys=consoleHandler,fileHandler,QHandler

[formatters]
# List of formatters
keys=simpleFormatter,noDateFormatter,ezFormatter

# ===================================================
[logger_root]
level=NOTSET
handlers=consoleHandler, QHandler

[logger_pyfdax]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.pyfdax
propagate=0

[logger_pyfda_class]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.pyfda_class
propagate=0

[logger_filter_factory]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.filter_factory
propagate=0

[logger_filterbroker]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.filterbroker
propagate=0

#-------------------- libs -------------------
[logger_pyfda_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_lib
propagate=0

[logger_pyfda_sig_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_sig_lib
propagate=0

[logger_pyfda_fix_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_fix_lib
propagate=0

[logger_pyfda_qt_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_qt_lib
propagate=0

[logger_pyfda_io_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_io_lib
propagate=0

[logger_pyfda_fft_windows_lib]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.pyfda_fft_windows_lib
propagate=0

[logger_tree_builder]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.tree_builder
propagate=0

[logger_csv_option_box]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.libs.csv_option_box
propagate=0

#-------------------- input_widgets -------------------
[logger_amplitude_specs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.amplitude_specs
propagate=0

[logger_freq_specs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.freq_specs
propagate=0

[logger_freq_units]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.freq_units
propagate=0

[logger_input_coeffs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_coeffs
propagate=0

[logger_input_coeffs_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_coeffs
propagate=0

[logger_input_fixpoint_specs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_fixpoint_specs
propagate=0

[logger_input_info]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_info
propagate=0

[logger_input_pz]
level=WARNING
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_pz
propagate=0

[logger_input_pz_ui]
level=WARNING
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_pz_ui
propagate=0

[logger_input_specs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_specs
propagate=0

[logger_input_tab_widgets]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_tab_widgets
propagate=0

[logger_select_filter]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.select_filter
propagate=0

[logger_target_specs]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.target_specs
propagate=0

#------------------- filter_widgets ---------------------
[logger_bessel]
level=INFO
handlers=fileHandler, consoleHandler,QHandler
qualname=pyfda.filter_widgets.bessel
propagate=0

[logger_equiripple]
level=INFO
handlers=fileHandler, consoleHandler,QHandler
qualname=pyfda.filter_widgets.equiripple
propagate=0

[logger_firwin]
level=INFO
handlers=fileHandler, consoleHandler,QHandler
qualname=pyfda.filter_widgets.firwin
propagate=0
#------------------- fixpoint_widgets ----------------
[logger_fir_df_pyfixp]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.fixpoint_widgets.fir_df.fir_df_pyfixp
propagate=0

[logger_fir_df_pyfixp_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.fixpoint_widgets.fir_df.fir_df_pyfixp_ui
propagate=0

[logger_iir_df1_pyfixp]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.fixpoint_widgets.iir_df1.iir_df1_pyfixp
propagate=0

[logger_iir_df1_pyfixp_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.fixpoint_widgets.iir_df1.iir_df1_pyfixp_ui
propagate=0
#-------------------- plot_widgets -------------------
[logger_mpl_widget]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.mpl_widget
propagate=0

[logger_plot_3d]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_3d
propagate=0

[logger_plot_fft_win]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.logger_plot_fft_win
propagate=0

[logger_plot_hf]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_hf
propagate=0

[logger_plot_impz]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_impz
propagate=0

[logger_plot_impz_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_impz_ui
propagate=0

[logger_plot_phi]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_phi
propagate=0

[logger_plot_pz]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_pz
propagate=0

[logger_plot_tab_widgets]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_tab_widgets
propagate=0

[logger_plot_tau_g]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_tau_g
propagate=0

[logger_plot_tran_stim]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.tran.plot_tran_stim
propagate=0

[logger_plot_tran_stim_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.tran.plot_tran_stim_ui
propagate=0

[logger_tran_io]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.tran.tran_io
propagate=0

[logger_tran_io_ui]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.tran.tran_io_ui
propagate=0

#------ Test Case, file doesn't exist -----
[logger_no_existo]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.no_existo
propagate=0
#------------------------------------------

# specify how to log to:  text console / logging file / GUI logging window
#
# For each handler, define the class (implementation), formatting (see next section)
# and the minimum logging level (defined by the higher of global and individual level,
# e.g. level=INFO prevents all DEBUG level messages).
#---- Console
[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=noDateFormatter
args=(sys.stdout,)
#---- File
[handler_fileHandler]
class=DynFileHandler # FileHandler is default
level=INFO
formatter=simpleFormatter
args=('pyfda.log', 'w', 'utf-8') # overwrites log file
#args=('pyfda.log','a', 'utf-8') # appends to log file
#---- GUI
[handler_QHandler]
class=QEditHandler
level=INFO
formatter=ezFormatter
args=()

#-------------------------------------------

[formatter_simpleFormatter]
format=[%(asctime)s.%(msecs).03d] [%(levelname)7s] [%(name)s:%(lineno)s] %(message)s
# for linebreaks simply make one!
datefmt=%Y-%m-%d %H:%M:%S

[formatter_noDateFormatter]
format=[%(levelname)7s] [%(name)s:%(lineno)s] %(message)s

[formatter_ezFormatter]
format=[%(levelname)7s][%(asctime)s.%(msecs).03d] [%(filename)s:%(lineno)d] %(message)s
datefmt=%H:%M:%S

pyfda_rc.py

Layout and some parameters can be customized with the file pyfda/pyfda_rc.py (within the install directory right now, no user copy).