Using WIDesigner - edwardkort/WWIDesigner GitHub Wiki

Introduction

WIDesigner is a Java application to assist the design of woodwind instruments. In its current version, it predicts instrument tuning over the full range of the instrument, and calculates instrument dimensions to optimize tuning accuracy over the full range. At present, it supports fipple flutes, transverse flutes, and single- and double-reed instruments. (The tuning models for transverse flutes and reeds would benefit from additional validation.) This page introduces the WIDesigner facilities for describing, evaluating, and improving, instrument designs.

WIDesigner supports four "Study Models," for four different classes of instruments. The NAF Study Model predicts a nominal playing frequency for each note, and offers geometry optimizers suited for the design of Native American Flutes. The Whistle Study Model and Flute Study Model predict a minimum and maximum playing frequency for each note along with a nominal playing frequency, and offer geometry optimizers for hole geometry and bore geometry. The Reed Study Model predicts a nominal playing frequency for each note, and also offers geometry optimizers for hole and bore geometry. The reed study model serves primarily single and double reed instruments, but can also be used on a limited range of lip reed instruments.

The WIDesigner Window

At the top of the WIDesigner window is a menu bar of pull-down menus--File, Edit, Tool, Window, and Help--and a toolbar of buttons that give direct access to some specific menu actions. Below these, the window has three parts:

  • The Study panel lists the instruments, tunings, and optimizers/constraints that you have available to you. New entries appear in these lists as you open or create instruments, tunings, and constraints. The Study panel is where you select what instrument, tuning, etc., you want to work with for a given action. Be sure the title at the top of this panel names the instrument class you want to work with; if it doesn't, please use Edit->Options... to select the right study model.
  • The Console panel is a running log of messages from WIDesigner. Pay particular attention to the messages logged after you run an optimization, to see how much the optimization improved the instruments tuning, if at all.
  • The rest of the window displays each of the files that you have open, as a set of tabbed panels.

Initially, the Study panel is on the left side of the window, and the Console is on the bottom. Although you can move all of these panels around the window, and even to other parts of your computer display, we advise against trying this when you are starting out, as it may be difficult to get the panels back where you want them.

Starting Out

Suggested first steps with WIDesigner:

  • Download the latest release, read about the WIDesigner Release Package and Sample Files, and follow the instructions in the installation video.
  • Use the WIDesigner options dialog to pick the study model for the class of instrument you are working with (NAF, Whistle, Flute, or Reed), and to review the other options.
  • Open an instrument file and a tuning file from the sample files delivered with the release. Use the GUI to alter the instrument and the tuning to suit your needs, and use File-->Save As... to save the new instrument file and the new tuning file.
  • Use the WIDesigner tools to evaluate how well your instrument design matches the desired tuning.
  • To see if you can improve the instrument design, decide what instrument dimensions you want to work with. We suggest hole sizes and spacing as a good place to start. The different study models have different optimizers; select an optimizer that works with your chosen instrument dimensions. For the NAF Study Model, you also need to create a set of constraints for your chosen optimizer. Optimizers for other study models each come with a built-in set of default constraints.
  • Run the optimizer to produce a new instrument design. Use the modelling tools to evaluate the tuning of the new design.

Learning More

WIDesigner Options describes how to choose a study model, and set other WIDesigner parameters. See WIDesigner Video Tutorials for links to YouTube videos describing how to use the program, including general videos, and tutorials for the NAF study model. Using the Tuning File Wizard describes the wizard pages that facilitate the process of generating a WIDesigner tuning file for your instruments. The Glossary defines some of the terms that appear on WIDesigner displays.

Working With the Whistle Study Model introduces the whistle study model, with links to tutorials on using it. Similarly, Working With the Flute Study Model introduces the flute study model, with links to the tutorials, and Working With the Reed Study Model introduces the reed study model. Optimizers in the NAF Study Model, Optimizers in the Whistle and Flute Study Models and Optimizers in the Reed Study Model are reference pages for the optimization tools WIDesigner supports. WIDesigner Optimizers gives some background about what exactly WIDesigner is optimizing, and how.

The written tutorial pages include instructions on [Optimizing a Whistle or Flute Design]], and information on the evaluation tools: [[Evaluating Instruments with the Tuning Table and Tuning Graph]], [[Reading the Note Spectrum Graph]], and [the Supplementary Information Table.

WIDesigner, latest release provides the latest release of the software, sample files, and source code.

See the Bibliography for published work describing the acoustic models in WIDesigner.

Data Files

WIDesigner stores three types of data in XML files. Users can display and edit each type of file either using the WIDesigner GUI panels, or directly as XML. Users can open one or more files of each type. WIDesigner lists the open files of each type in the left-hand Study panel. Users select specific files to work with from the Study panel.

Instrument files record the description and geometry of an instrument, including the number of holes and their size and positions, and any changes in bore taper. Positions are all measured from the same origin at the mouthpiece end of the instrument toward the open end of the bore. While you may use whatever origin you find convenient, for fipple flutes we generally use the position of the sound blade or splitting edge at the bottom of the window or "true sound hole". For fipple flutes, this is the reference point for defining the mouthpiece position, so all of the examples have Mouthpiece Position set to 0.0. For transverse flutes, the reference point for Mouthpiece Position is the centre of the embouchure hole. For reeds, WIDesigner requires that the mouthpiece position equals the position of the uppermost bore point. See the glossary for definitions of the instrument dimensions that WIDesigner records.

To open an instrument file, use File-->Open or the Open icon on the toolbar, then select the file using the pop-up dialog. You can also use drag-and-drop to drag the file from a file manager or Windows Explorer and drop it on the WIDesigner GUI. At this time, WIDesigner doesn't have a process to create an instrument file from scratch.

Tuning files record the tuning of notes in the scale of an instrument for specific note fingerings. Tuning files come in three varieties:

  • Most often, the Frequency column in a tuning file gives the target playing frequencies of a properly tuned scale. Use these tuning files for evaluating instrument performance, and optimizing instrument designs.

  • The Frequency column can instead give measured frequencies that you have recorded for a specific instrument. Use these tuning files only with the applicable instrument calibrator for calibrating the instrument model.

  • For the whistle and flute study models, the tuning file can have target frequencies in the Frequency column, and measured minimum and maximum playing frequencies for a specific instrument in the Min Freq and Max Freq columns. You can use these tuning files for both calibration and optimization, because the calibrator will use Min Freq and Max Freq, while the optimizers use the target frequency.

To open a tuning file, use File-->Open or the Open icon on the toolbar, then select the file using the pop-up dialog. You can also use drag-and-drop to drag the file from a file manager or Windows Explorer and drop it on the WIDesigner GUI. To create a new tuning file from basic parts, use File-->New Tuning... to launch the Tuning File Wizard. In the name or description field, be sure to specify whether the file contains target frequencies (for optimization), measured frequencies (for calibration), or target frequencies plus measured min/max frequencies.

Constraint files record upper and lower bounds to be placed on each geometry dimension when optimizing an instrument design.

To open a constraint file for an optimizer, select the optimizer in the Study panel, and use File-->Open constraints.... You can create a new constraints tab for the selected optimizer using either File-->Create default constraints or File-->Create blank constraints. Create default constraints supplies default values for all of the constraints on the tab; Create blank constraints supplies neutral values such as zero and one for all the constraints. After modifying constraint values to suit your needs, use File-->Save-as constraints... to save a new constraints file in the appropriate directory.

Calibration Factors

In our experience, the physical mouthpiece dimensions captured in an instrument file don't entirely explain the instrument tuning. To improve the tuning predictions from the WIDesigner model, each study model includes one or two calibration factors in the instrument definition. The wiki pages for different study models suggest an appropriate starting value for each factor. You may find these starting values perfectly adequate for your needs. However, if you want to improve the calibration of the WIDesigner model from these starting values, each study model has a calibration process to adjust the calibration factors. In general:

  • Measure the tuning of the instrument, and enter the tuning in a tuning file.
  • Run the calibrator that appears at the top of the list of optimizers for the study model. The calibrator produces a new instrument definition with adjusted calibration factors.

Before an instrument is built, you can run this calibration on any instrument with a similar mouthpiece, to get suggested calibration values. While an instrument is under construction, you can start calibrating the model as soon as the instrument can produce a few notes, or even one note plus a few overtones.

Modelling Instrument Tuning

Once the user selects an instrument and tuning in the Study panel, WIDesigner offers several tools on the Tool menu to model instrument behaviour, and evaluate how well the chosen instrument plays according to the chosen tuning. In general, each tool displays results in a new pop-up window, but does not shift focus to that window.

Tool-->Calculate tuning displays an instrument tuning table in a new window, comparing predicted and target tuning. The NAF study model displays playing frequencies only. For the whistle and flute study models, the tuning table displays playing frequencies, along with minimum and maximum frequencies for each note.

Tool-->Graph tuning displays a graph of instrument reactance as a function of frequency for the notes in the tuning. This tool is most useful with the whistle and flute study models.

Tool-->Sketch instrument displays a scaled diagram of the current instrument.

Tool-->Graph note spectrum displays a graph of the impedance spectrum for a selected fingering.

Tool-->Supplementary Info displays a table of additional information calculated from the tuning model. (The mathematical models used to calculate this information are somewhat speculative, so it should be used with caution.)

Optimizing Instruments

For each study model, WIDesigner offers a set of instrument optimizers, displayed on the Study panel. Each optimizer varies specific aspects of the instrument geometry, to produce an instrument that plays as close as possible to the selected tuning. Typical optimizers vary hole sizes, hole positions, bore profile, or some combination of these. Optimizers in the NAF Study Model, Optimizers in the Whistle and Flute Study Models and Optimizers in the Reed Study Model describe the optimizer choices in more detail.

Select an optimizer in the Study panel, along with an instrument and a tuning, and use Tool-->Optimize instrument to run the specified optimization. WIDesigner creates a new instrument definition as a new tabe in the main window, and adds this instrument to the list in the Study panel. The Console panel displays the outcome of the optimization.

Select the new instrument (called Untitledn) in the Study panel and click Tool-->Calculate tuning or Tool-->Graph tuning to evaluate the optimized instrument.

To compare the optimized instrument with the original, select the original instrument in the Study panel and the tab for the optimized instrument in the main window, and click on Tool-->Compare instruments.