User Manual

This part of the documentation is intended to describe the features of pyFDA that are relevant to a user (i.e. non-developer).

Once you have started up pyFDA, you’ll see a screen similar to the following figure:

pyfda screenshot

Fig. 2 Screenshot of pyfda

  • Inputs widgets: On the left-hand side you see tabs for different input widgets, i.e. where you can enter and modify parameters for the filter to be designed
  • Plotting widgets can be selected on the right hand side of the application.
  • Logger window is in the lower part of the plotting window, it can be resized
    or completely closed. The content of the logger window can be selected, copied or cleared with a right mouse button context menu.

The invidual windows can be resized using the handles (red dots).

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 = 2

#------------------------------------------------------------------------------
# Define variables than can be read in other sections by e.g. IIR_DF1 = ${Common:IIR}
#------------------------------------------------------------------------------

# 
IIR = [Bessel, Butter, Cheby1, Cheby2, ellip]
FIR = [Equiripple, Firwin]

#------------------------------------------------------------------------------
# Add user directory(s) to sys.path (optional):
#------------------------------------------------------------------------------
#
# Specify relative or absolute path(s) to one or more user directories. When the
# directory contains one or more of the following subdirectories, these are
# searched for corresponding user widgets:
#
# input_widgets    # widgets for specifying filter parameters
# plot_widgets     # widgets for plotting filter properties
# filter_designs   # 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. This attribute
# 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_files
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
# myplot # this could be the name of a user module
plot_pz
plot_impz
plot_3d

########################
[Filter Designs]
########################
# The specified filter design modules (files) are searched for in sys.path 
# and in subdirectories / subpackages named "filter_designs".
#
# 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_direct']}
bessel : {'fix':['IIR_cascade', 'IIR_direct']}
butter
cheby1 : "yet another option"
cheby2 : {'fix':'IIR_Special'}
ellip
ellip_zero

# --- FIR ---
equiripple :
firwin : 
ma

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


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

# iir_df1 = ${Common:IIR}
fir_df = ${Common:FIR}
delay1 = 'Equiripple'

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, tree_builder, filter_factory, filterbroker, pyfda_versions, 
     pyfda_lib, pyfda_fix_lib, pyfda_qt_lib, pyfda_io_lib, 
     input_tab_widgets, input_specs, select_filter, input_files, input_info, input_pz,
       target_specs, amplitude_specs, freq_specs, freq_units, input_coeffs,
       input_fixpoint_specs,
     ellip,
     fir_df, fixpoint_helpers,
     plot_tab_widgets, plot_hf, plot_phi, plot_tau_g, plot_impz, plot_impz_ui, 
       plot_pz, plot_3d, mpl_widget, 
     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_tree_builder]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.tree_builder
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

[logger_pyfda_versions]
level=INFO
handlers=fileHandler,consoleHandler, QHandler
qualname=pyfda.pyfda_versions
propagate=0

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

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

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

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

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

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

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

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

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

[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_info]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.input_widgets.input_info
propagate=0

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

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

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

#------------------- filter_design ---------------------
[logger_ellip]
level=INFO
handlers=fileHandler, consoleHandler,QHandler
qualname=pyfda.filter_design.ellip
propagate=0

#------------------- fixpoint_widgets ----------------
[logger_fixpoint_helpers]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.fixpoint_widgets.fixpoint_helpers
propagate=0

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

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

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

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

[logger_plot_tau_g]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_tau_g
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_pz]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.plot_pz
propagate=0

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

[logger_mpl_widget]
level=INFO
handlers=fileHandler,consoleHandler,QHandler
qualname=pyfda.plot_widgets.mpl_widget
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).