# The QBrew Handbook

David Johnson

    david@usermode.org

1999 - 2008 David Johnson

Permission to use, copy, modify and distribute this document for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies.

## Introduction

&qbrew; is a homebrewer's recipe calculator. With it a brewer can formulate new recipes and calculate gravity, bitterness, color and other attributes.

No payment or registration is required for &qbrew;, but the author would be extremely delighted to receive spontaneous and voluntarily donated bottles filled with homebrew. Photos of such bottles will do in a pinch. If you wish to contribute to the further inebriation of the author, please send mail to david@usermode.org requesting a physical address to send the bottles to.

The homepage for QBrew is http://www.usermode.org/code.html

Code and cash contributions will, of course, grease the wheels of QBrew development.

## Using &qbrew;

### Recipes

#### Basic Recipe Details

Enter in the basic recipe details in the top section of the program window. There are fields for the title of the recipe, the name of the brewer, recipe style, and batch size.

The name of the recipe and the brewer are for identification purposes only. The recipe style will display the appropriate style parameters in the characteristics area. The batch size affects many calculations.

#### Recipe Ingredients

Recipe ingredients are added using the bottom section of the program window. There are tabs for grains and other fermentables, hops, and miscellaneous ingredients.

You can edit any field of an ingredient by double clicking within it. To enter a new ingredient, double click in the name field of a blank row. To remove an ingredient, set its name field to a blank.

The Notes tab of this section allows you to enter notes on the recipe and batches. These could be specific brewing procedures, brewing and bottling dates, or measured gravity. They are saved along with the recipe, but otherwise do not affect it.

#### Recipe Characteristics

The middle section of the program window details your recipe's characteristics. Information included here are the recommended gravity, bitterness and color for the selected recipe style, as well as the calculated gravity, bitterness, color and alcoholic content for your recipe.

### Miscellaneous

#### Alcohol Percentage Tool

You can calculate the actual alcohol percentage in a batch by using the Alcohol Percentage tool under the Tools menu. Enter in your measured original gravity and final gravity. The percentage of alchohol by volume and by weight will be calculated.

#### Hydrometer Correction Tool

You can access the Hydrometer Correction tool under the Tools menu. This tool is useful for converting your actual hydrometer readings to the correct value. Enter in the temperature at which you took the sample, the temperature at which the hydrometer is calibrated (typically 60° or 68° Fahrenheit), and the actual hydrometer reading. The corrected reading will be calculated.

#### QBrew Data

The data that &qbrew; uses is in the file `qbrewdata`, typically located under the install directory in Windows, as part of the application bundle under Macintosh OSX, and under `/usr/local/share/qbrew` under traditional Unix. If there exists a file in the user's home directory with the name of `.qbrewdata`, then this file will be used instead.

The Database Editor, under the Tools menu, may be used to edit the users's `.qbrewdata` file. The operation of the editor is similar to editing ingredients in a recipe. In addition there is a Style page for editing recipe styles.

#### US/Metric Conversions

US units of measurement are used by default in &qbrew;. This can be changed in the configuration dialog. Both US and Metric measurements are available.

Please note that converting from one system to another and back may result in round-off errors during the conversion.

#### Exporting and Importing Data

QBrew will import BeerXML recipes, and export native recipes to HTML, PDF, BeerXML or plain text format. BeerXML is a new format designed for sharing recipes and other brewing data. QBrew supports version 1.0.

Importing or exporting a recipe will result in some loss of data. This is because brewing programs all have different underlying assumptions and models for the data. Because of this, QBrew recipes should be stored in the native QBrew format, and only exported for sharing or posting recipes.

## &qbrew; Reference

### The Menus

#### The File Menu

`File->New (Ctrl+N)`

  This creates a new empty recipe. If there is a current recipe with unsaved changes the user is given a chance to save it.

`File->Open (Ctrl+O)`

  This opens an existing recipe. Use the Open dialog to select the recipe you wish to open.

`File->Open Recent`

  This is a shortcut to open recently saved recipes. This item opens a list with several of the most recently saved recipes to choose from.

`File->Save (Ctrl+S)`

  Saves the current recipe. If this is the first time the recipe has been saved, the Save As dialog (described next) will be shown.

`File->Save As...`

  Saves the recipe under a new file name. A Save As dialog will be shown to select the name of the file to save to.

`File->Export...`

  Exports the recipe to a different format. This command will display the Export dialog, which is very similar to the Save As dialog.

`File->Print Preview...`

  Display a print preview dialog. This dialog can be used to preview the recipe before printing.

`File->Print... (Ctrl+P)`

  This prints the recipe. Opens a print dialog allowing the user to specify where and how to print.

`File->Quit(Ctrl+Q)`

  Quits &qbrew;. If you have unsaved recipes, you will be prompted to save them.

#### The Tools Menu

`Tools->Alcohol Percentage...`

  Brings up the Alchohol Percentage tool. This is used to calculate alcohol percentage by weight or volume, from measured specific gravity readins.

`Tools->Hydrometer Correction...`

  Brings up the Hydrometer Correction tool. This is used to correct hydrometer readings taken at temperatures other than the calibrated temperature.

`Tools->Database Editor...`

  Brings up the Database Editor tool. This is used to edit the database of ingredients and styles.

#### The Options Menu

`Options->Main Toolbar`

  Toggle the main toolbar on and off. When unchecked the toolbar is hidden.

`Options->Statusbar`

  Toggle the status bar on and off. When unchecked the status bar is hidden.

`Options->Configure...`

  This configures settings for &qbrew;. A dialog is shown to configure general, recipe and calculation related settings.

#### The Help Menu

`Help->Contents (F1)`

  Opens up a help window and displays this document.

`Help->Primer`

  Opens up a help window and displays a brewing primer.

`Help->What's This? (Shift-F1)`

  Brings up a cursor you can use to find out what various controls and objects in the application do. Clicking on an item within &qbrew; will pop up a small window with help on that item.

`Help->About...`

  Displays copyright and other basic information about &qbrew;

### Configuration

The Configuration dialog is used configuring &qbrew;. There are four buttons on the bottom of the dialog. Pressing the OK button will apply all settings and close the dialog. Pressing the Reset button will reset the dialog to default values. Pressing the Apply button will apply the settings, but not close the dialog. The Cancel button will close the dialog without applying the settings.

Configuration changes are automatically saved when the OK button is pressed.

#### General Configuration

The "Look and feel" control allows you to change the look and feel (theme) of &qbrew;. "Show splash screen" lets you choose to display or not display the program startup splash screen.

The "Recent files" control selects the number of files displayed in the "Open Recent" menu. The "Enable autosave" controls set whether automatic saving of the current recipe is done, and how often. The "Enable autobackup" control sets whether recipes are automatically backed up. The "Load last file" control determines whether the previously used recipe is automatically loaded upon program startup.

#### Recipe Configuration

The "Recipe Defaults" section sets some default recipe values. These settings only affect new recipes or ingredients. They include "Batch size", "Recipe style", and "Hop type".

#### Calculation Configuration

Use the "Measurement units" control to set the measurement units you will be using (US or Metric). Use the "Tinseth" and "Morey" controls to alter the bitterness and color calculations. "Efficiency" sets the mash efficiency for calculations.

## Designer's Notes

&qbrew; aims to be a simple streamlined homebrewing recipe calculator. As such, it doesn't include features that other software designed for professional brewing might include. This is not a flaw on the part of &qbrew;, but a conscious choice to moderate the scope of the software. Emails and forum posts praising the &qbrew; interface tell me that his was a good decision.

### Grain Calculations

The basic gravity calculation is the sum of all grains' extract times quantity, divided by the batch size. Mashed grains will have their extract modified by the mash efficiency. Steeped grains will use a lesser efficiency, typically half of their extract.

The color calculated is in SRM, not in HCU (homebrew color units). HCU is the sum of all grains' color times quantity, divided by the batch size. This is only accurate for very low color values. The default conversion to SRM uses the formula discovered by Ray Daniels, which is SRM=(MCUx0.2)+8.4 (for values of HCU over 8.0). An alternate color calculation discovered by Dan Morey is SRM=1.4922x[(MCU)^0.6859] (for values of SRM less than 50). To change to the Morey method, open up the `Configure...` dialog and check the `Use Morey color calculation` box. More information on color calculations can be found at "Approximating SRM Beer Color" <http://hbd.org/babble/Color.htm>, and "Beer's Law" <http://www.brewingtechniques.com/brewingtechniques/beerslaw/morey.html>.

Final gravity is assumed to be 25% of the OG. Looking through the AHB style guide, this is the same assumption they made. The alcoholic content calculations were derived from Noonan's New Brewing Lager Beer, and based on this FG assumption.

### Hop Calculations

There are two different methods used to calculate hop bitterness. The default IBU calculation uses the Rager method, from Norm Pyle's "Hops FAQ" <http://realbeer.com/hops/FAQ.html>. The other method is the Tinseth method, from Glen Tinseth's "Hop Page" <http://realbeer.com/hops/>. To change to the Tinseth method, open up the `Configure...` dialog and check the `Use Tinseth bitterness calculation` box. The utilization table for the Rager method can be edited by changing the appropriate area of the `qbrewdata` file.

Please see the above links for details on these formulae, as they can be a bit complex.

## Questions and Answers

Why don't the results on the Alcohol tool match the Characteristics section of the main window?

It's the curse of rounding errors! When you use the Alcohol tool you are entering in gravity values with a precision of two decimal places. But your recipe in QBrew is stored with a much higher precision than this, even though it is displaying characteristics with a lower precision.

I get hundreds of errors when I try to compile &qbrew; under Unix. What am I doing wrong?

&qbrew; has been successfully compiled and run on a variety of Unix platforms, so the odds are low that something's wrong with configure (although it does happen). More likely, you don't have the necessary libraries or headers installed. Make sure that you have the X development libraries installed, as well as the Qt &qt.version; or greater development libraries. &qbrew; will not compile and link with the older Qt 3.x libraries.

There are many useful options in the configure script. These options can be displayed by running `./configure --help`. Also please read the INSTALL file for several useful tips.

If you are still having problems after this, then write me at qbrew@usermode.org. Please include the full text of the error message, along with the `config.log` in the build directory.

Why don't you distribute &qbrew; as a DEB or RPM file?

I do make packages available for Windows and Mac OSX. I am doing this because users of those platforms are unaccustomed to building software. It is more difficult to do this under Linux and Unix because there are so too many different varieties available. I cannot possibly distribute binary packages for each system and distribution while trying to keep up with changing versions.

At this time, &qbrew; is already available prepackaged for Debian GNU/Linux, SuSE Linux, Linspire, NetBSD and FreeBSD. If you distribution does not have a &qbrew; package, you may wish to consider maintaining one for them. Please note that the available binary packages are not always the most recent &qbrew; version.

## Credits

### Helpful Folk

I would like the thank the following people for their outstanding help with the creation of &qbrew;...

- ...Abe Kabakoff for contributing several formulae and the Correction tool.

- ...Michal Palczewski for contributing bug fixes and the Alcohol tool.

- ...Lee Henderson, Rob Hudson, and Kevin Pullin for contributing bug fixes.

- ...Tobias Toedter for German translation work.

- ...Stephen Lowrie for a lot of rote work with the `qbrewdata` file, as well as major portions of the brewing primer.

- ...the various maintainers for &qbrew; packages.

- ...The numerous users who have written me and kept my spirits up.

### Copyright

Copyright © 1999 - 2008 David Johnson, All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This product contains software written by Abe Kabakoff <abe_kabakoff@gmx.de>, and Michal Palczewski <michalp@gmail.com>