Hash – an object's identity

Hash definition

A Hash, sometimes called also hash code, is the "unique signature" or "identity" of an object.

The hash is generally a string (a text) containing alphanumeric characters. It is composed by applying a Hash algorithm to an object, which parses the input object, all its properties, and the values assigned to those properties. The returned hash is a "combination of all the variables" present in the object. It follows that its most important feature is that the hash remains the same as long as the object remains the same (under certain criteria, which can be customised).

The Hash for objects can be used in many different kinds of comparisons, or for any case where a unique identification of an object is needed. Examples include: - you can compute hash for objects to quickly and safely compare objects with each other, so you can determine unique objects (i.e., what objects are duplicates or not) - you can compare an object's hash at different points in time. You can store the hash of an object in a certain moment; then, some time later, you can check if the object changed (i.e., even a slight variation of one of its properties) by checking if its hash changed.

BHoM's Hash() method

BHoM exposes a Hash() method to calculate the Hash for any BHoM object (any object implementing the IObject interface).

This method is defined in the base BHoM_Engine: BH.Engine.Base.Query.Hash(). Here is an example of how the method can be used in Grasshopper:

The method returns a string, a textual Hash code that uniquely represents the input object.

This method's most parameters are: - the IObject you want to get the Hash for; - comparisonConfig configurations on how the Hash is calculated (see the dedicated section); - hashFromFragment: if instead of computing the Hash of the object, you want to retrieve a Hash that was previously stored in the object's Fragments.
In order to set the HashFragment on a BHoMObject's Fragment, you can use the SetHashFrament() method:

Hash ComparisonConfig: options to compute the Hash

The real potential of the Hash algorithm is given by its customisation options, which we call ComparisonConfig (comparison configurations).

For example, you may want to configure the Hash algorithm so it only considers numerical properties that changed within a certain tolerance. This way, you can determine if an object changed by looking at changes in the Hash, and you will be alerted only if the change was a numerical change greater than the given tolerance.

For this reasons, we expose many configurations in a ComparisonConfig object:

See the page dedicated to ComparisonConfig for details on it.

Note that some ComparisonConfig options may slow down the computation of the Hash, which becomes particularly noticeable when hashing large sets of objects. An option that may have particular negative impact when computing the Hash is PropertiesToConsider, as explained here.

Note for developers: customising an object's Hash

If you want a specific object to be Hashed in a particular way, you can implement a specific HashString() method for that object in your Toolkit.

Here is an example for Revit's RevitParameter object. The HashString() method will get invoked when computing the Hash().

More info in the Diffing and Hash: guide for developers wiki page.