Add a new property

Follow these steps to add and configure a new property:

1. Open Property Manager

   Open the property manager by clicking the Properties button in the Managers group of the Reference Data ribbon tab.

   

2. Add property

   To add a new property, click the button in the bottom left corner. The New Property dialog box opens.

   

3. Enter Name, Unit Category and DLL Code

   

   Enter the following information:

   • Name: A name for the property.

   • Unit Category: The unit category for the property defines the type of measurement that the new property corresponds to. For example, a property such as Pour Point would have a unit category of Temperature, while a property such as Pour Point Index would be Graph property manager.

   • DLL code: The DLL code enables you to use your new property in code developed using the Assay SDK. The DLL code can be any meaningful text of your choice.

     Click OK. The property is added to the list of properties on the left hand side of the Property Manager.

     A corresponding property is automatically created in the graph property list. See Configure graph property attributes in Graph property manager.

4. Enter Short Name and Description

   In the General category, enter a Short Name for your property. The short name will be used in reports and other areas where an extended, long name might not fit neatly into the space available.

   

5. Enter boiling point ranges

   The check boxes associated with the fields Cuts, Residues and Whole crude value allow you to define boiling ranges that are normally measured for that property.

   

   To define a boiling range select the check box for the type and, if needed, enter the acceptable cut points. You must also choose the appropriate temperature unit for measurement of the boiling point.

Example

Basic nitrogen is declared as usually being measured for any cuts whose initial and final boiling points lie between 200 and 550ºC. For example, a cut 300-400°C is normally measured, but it would be unusual to measure the basic nitrogen of such cuts as IBP-300°C, 150-300°C, 300°C+, 300-600°C. Similarly, residue cuts such as 350°C+ may be expected to be measured,whereas 250°C+ would not be. The unchecked whole crude value box shows it would be unusual to measure the whole crude value.

The boiling point range is used only to control shading of the Measurement Grid, indicating property/cut combinations which would normally be measured. If a particular property/cut combination is not normally measured (that is a cut for that property is not in the boiling point range as defined for that property), then the cell in the grid is shaded slightly grey. Values may still be entered in the cell for that property/cut combination, and these values will be used during generation.

In the above example, the basic nitrogen cell of a cut IBP-70° would be shaded dark grey, indicating the basic nitrogen is not normally measured for this cut, and if a value were entered in the cell the basic nitrogen measurement would be used during assay generation along with the other measurements.

6. Enter value ranges

   The value range section allows you to set 2 acceptable ranges of your property: a warning range and an invalid range.

   • Invalid Measurements will be highlighted in red and ignored during assay generation. If a property is modelled or based on a correlation, generation results may be returned in the measurement grid, but these are for reference only and are not used during generation.

   • Warning Measurements will be underlined in the grid, but are still used during assay generation. Warning ranges only apply to AssayEditor documents.

   Normally the product checks to see if entered values are valid by comparing the entered value to expected values found in the statistical model. For example, your statistical model may contain crudes with whole crude sulphur values between 0% and 4%. If a whole crude sulphur value of 12% is entered, this is outside the range expected so would be highlighted as a warning. This method of warning checking only applies to Documents based on the statistical model, such as AssaySynthesis and ProductSynthesis.

   For AssayEditor documents which do not use the statistical model, the entered value is checked against the warning range entered in the property manager. For example, if the warning range for sulphur in the property manager is set as 0% - 3% then entering a whole crude sulphur value of 9% will show a warning for that value.

7. Choose display settings

   The final part of the General page allows you to choose the unit in which values for measurements or cuts of this property are displayed by default. This setting can be overridden in the measurement grid to display the property in any of the other possible units.

   You can also choose a display format for values for this property. Choose between various numbers of decimal places, significant figures or scientific notation. See Formats..

   

8. Choose blending behaviour

   Blending behaviour can be configured in the Blending section of the Calculations page.

   

   You can choose the basis for blending (both within a crude, and between crudes) as one of the following blend types:

   • Weight - blending is linear by weight

   • Volume - blending is linear by volume

   • Mole - blending is linear by mole

   • None - the blending behaviour cannot be defined

   • Wgt or Vol - blending is linear by weight or volume

   Since the units editor allows you to define non-linear unit transformations, you must specify the unit with respect to which blending is considered linear. The Linear As option allows you to specify this unit. In this example, any unit is acceptable (since transformations between units are linear). See Configure your units of measurement.

   Alternatively, if a blending index is used to linearize the blending, this option may be specified and the blending index explicitly entered, using the variable X to represent the property value expressed in the chosen unit. Any mathematical expression may be used. See Writing formulae.

   Finally, some properties are best handled by assuming that the fitted profiles should blend back to crude. This means that, given the profile, the value returned should correspond to the measured whole crude value upon integrating the whole profile with respect to the relevant yield curve. Simple properties, such as sulphur measurement and metals measurement, will have this box checked. Other values, such as pour point, are not normally expected to behave in this way, even when handled using a blending index. In these cases this setting would normally not be enabled.

   This setting is controlled via the Blends back to whole crude value in Edited Profiles checkbox. Note that this setting applies only to manually edited property profiles.

   In depth

   Blending refers to the mixing of crude oils or products to form a blend. To predict the property values for a blend, it is necessary to know how the various properties of interest combine. For linear properties, such as sulphur content, metals content, paraffinic content and carbon content, the computation used involves nothing more complex than products

   and sums. However, for non-linear properties, such as pour point, cloud point, viscosity, octane number and refractive index, no such simple computational process exists.

   The conventional approach to computing non-linear properties of a blend is to apply a blending index to these properties. This is a mathematical formula that transforms the value

   (such as viscosity) to a value that blends linearly. A range of well-established industrystandard blending indices exists, which have been determined by careful laboratory research.

   Assay is distributed with a range of such indices for the blending of non-linear properties. Assay's methods thus have the power, on the basis of measurements for blends and blend

   constituents, to determine blends robustly. At the same time, the blending indices employed by Assay are entirely customisable (in a similar way to correlations), if you have your own

   blending indices you would prefer to use.

   

   Tip Blending Rules for common properties are summarized in the Appendix. See Blending rules.

9. Choose correlations

   If required, you can choose correlations for the property in the Correlations section of the Calculations page.

   

   It is often the case that no measurements are available for a particular property for a particular crude. Unless specified otherwise through this correlations section, in such cases, no values would be generated for that crude.

   In practice, you might want to calculate the property value from other known values, in the case where it is absent. You can add a number of correlations by selecting from the list of valid correlations presented on pressing the Add button. In the case of absent data for this property, the correlations will be evaluated in order until a value is generated. See Add new correlations.

   Correlations can be removed from this list using the Remove button, and reordered by using the and buttons.

10. Specify test methods

    You can edit, add and remove test methods from the Test Methods page.

    

    For each test method, tick marks in the last three columns of the table show whether it applies to the whole crude, to distillates, or to residues. To remove a test method, click on it to select it and do one of the following:

    • Click the Remove button.

    • Right click on the method and choose Remove from the menu.

    • Press the Delete key on your keyboard.

    Note that you cannot remove the Default test method.

    To add a test method, do one of the following:

    • Click the Add button.

    • Right click anywhere in the test methods table and choose Add from the menu.

    • Double click in an empty area of the test methods table.

    The Test Method Editor dialog window will open, allowing you to define the new test method.

    To edit a test method, click on it to select it and do one of the following:l Click the Edit button.

    • Click the Edit button.

    • Right click on the method and choose Edit from the menu.

    • Double click on the method.

    The Test Method Editor dialog window opens, allowing you to edit the test method.

    

    From the Test Method Editor dialog window you can configure the following:

    • Test Method: choose a test method from the drop-down menu.

    • Precision: write a precision formula for the test method. For example, if you require a precision of either 5% relative to the measured value, or 1 ppm, whichever is greater, this can be entered as max(1,0.05*X), where X is the measured value in ppm. The full range of possibilities for the formulae which may be entered is indicated in the Appendix. See Writing formulae.

    • Applies to: choose whether this test method applies to Whole Crude, Distillates or AssayEditor, by selecting the corresponding check boxes.

11. Specify constraints

    When profiles are fitted for this property, a number of complex constraints may be specified to govern the nature of the curve fitted. See AssayEditor to understand the fitting process.

    You can add, edit or remove 3 types of constraints from the constraints page:

    • Value between - an upper and lower bound may be specified for the profile values for this boiling point range.

    • Value fixed - a fixed value may be specified for this boiling point range

    • Monotonicity - behaviour of the profile may be constrained to be monotonically either increasing or decreasing in this boiling point range.

    

    

12. Specify fitting behaviour

    Control the default tension by using the slider on the Profile Fitting page.

    • When the tension is low, the fitted profiles try to match the measured values and guide points faithfully.

    • When the tension is high, smoothness of the profile shape becomes more significant and values may not be matched so closely.

    Note that this setting controls the default, and can be overridden at any time when fitting a profile.

    The extrapolation behaviour of the fitted profiles can be controlled in the Extrapolation section of the Profile Fitting page.

    Upper extrapolation corresponds to extrapolation beyond the highest specified boiling point (either for a measurement or a guide point), and lower extrapolation to extrapolation below the lowest specified boiling point.

    Specify 1 of 3 modes of extrapolation, for the lower and upper extrapolation behaviour separately:

    • Intelligent - extrapolation follows the natural tendencies of the data

    • Linear - extrapolation is constrained to be linear beyond the range of the data

    • Fixed - a value which the fitted profile should take may be explicitly specified for the extrapolated range. In this case, the fixed value and associated unit may be entered in the corresponding boxes.

The product allows you to specify with a formula exactly what the precision associated with the measurement should be. See Writing formulae.