Settings Files

Calculon can be fully customized by editing its XML based settings files. This includes defining constants, functions, units and conversions. Following is a brief overview of the settings file structure.

General info

The settings files are read sequentially. This means you have to define something before using it. You can have multiple blocks of the same type.

All files with the extension .xml in the settings directory are read in alphabetical order. You’ll most likely want to define e.g. currencies in currencies.xml and so on for clarity.

Functions and constants

Functions are defined in the Functions section. Each function is defined in its own Functions block, with the contents of the block defining the actual function. The following should be self explanatory:

<Functions>
  <Function Name="power" Parameters="x y" Description="Raises x to power y"> x^y </Function>
</Functions>

Constants are defined as functions that take zero parameters. For example, pi is defined in the default settings file like this:

<Function Name="pi"> 3.141... </Function>

Quantities and units

Calculon treats units as entities belonging in a quantity class. Conversions between units of the same quantity are always possible. To convert between quantities a suitable conversion has to be defined.

Defining quantities

Quantities are simply blocks inside a root level Units block that contains one or more units. A block of same name can be defined multiple times, which does not replace the earlier block but simply adds more units among the existing units.

The Quantity requires the attribute Name.

<Quantity Name="Length"></Quantity>

Defining Units

Units are defined by the Unit tag as follows:

<Unit Symbol="m" Name="metre" Description="a metre is a thousand of a kilometre"> 0.001 km </Unit>

The most simple way to define units is to tell Calculon how it compares to known units. For example, one metre is defined in the default settings as 0.001 kilometers. Note how in the below example, one kilometre is one one arbitrary “unit”. Conversely, it could be defined that one metre is 1 “unit” and one kilometre is 1000 metres.

<Quantity Name="Length">
  <Unit Symbol="km" Name="kilometer">1</Unit>
  <Unit Symbol="m" Name="metre">0.001 km</Unit>
</Quantity>

When defining units that are not simply scaled versions of existing units, there are two more ways to define them. Both are example based approaches, you simply specify one or two values that match existing units.

Again, in the following example, one degree Celsius is defined as 1. However, since neither kelvin or Fahrenheit does not match up with Celsius in that zero degrees F would equal zero degrees C (as it is with e.g. centimeters and inches), we tell Calculon to fit the units using example value pairs. Note that the syntax is strict.

<Quantity Name="Temperature">
  <Unit Symbol="C" Name="degrees Celsius">1</Unit>
  <Unit Symbol="K" Name="kelvin">0 K = -273.15 C</Unit>
  <Unit Symbol="F" Name="degrees Fahrenheit">32 F = 0 C, 212 F = 100 C</Unit>
</Quantity>

Also, if there are suitable conversions defined, units can be defined by using them for maximum convenience. Consider the following example:

<Unit Symbol="m3" Name="cube metre"> 1 m * 1 m * 1 m </Unit>

Writing 1 m * 1 m * 1 m certainly is more convenient and also more informative than writing 1*10^-9 km3, eh?

Conversions between quantities

For arithmetics between two incompatible units (e.g. multiplying velocity by time), conversions can be defined that basically tell Calculon to continue with the incompatible operation and set the result unit to something else. Conversions are defined by the Conversion tag contained in a Conversions block.

For example, a useful conversion is allowing multiplying velocity by time and converting the result to distance traveled (e.g. 50 miles per hour times one hour should equal 50 miles). Another useful conversion, as used in the above unit definition, is to convert from length times length to area.

The following two examples allow converting between velocity, length and time. Note that the reverse conversion has to be explicitly defined (on the other hand since multiplication is commutative, you don’t need to define Velocity * Time and Time * Velocity).

<Conversion Formula="Velocity * Time" Result="Length" />
<Conversion Formula="Length / Time" Result="Velocity" />