File Coverage

lib/Tribology/Lubricant.pm

Criterion	Covered	Total	%
statement	125	150	83.3
branch	34	54	62.9
condition	10	23	43.4
subroutine	15	18	83.3
pod	8	10	80.0
total	192	255	75.2

package Tribology::Lubricant;

=head1 NAME

Tribology::Lubricant - Data type that represents a Lubricant class.

=head1 DESCRIPTION

This class, given technical data based on lubricant TDS/PDS documents assists in calculation of various Rheologic characteristics of the lubricant. Such as:

=over 4

=item *

V-T behavior (C) using B equation

=item *

Calculate viscosity at a given temperature ( C ) when any of two calibration points are known

=item *

Calculate viscosity index using ASTM D2270's B and B procedures ( C )

=item *

Lookup B and B constants of the lubricant using ASTM D2270 Table and using linear interoplation whenever neccessary ( C )

=back

=head1 SYNOPSIS

    require Tribology::Lubricant;

    # We already have viscosity at 40C and 100C.
    my $lub = Tribology::Lubricant->new({
        label   => "Naphthenic spindle oil",
        visc40  => 30,
        visc100 => 100
    });

    # Viscosity @ 50C:
    my $visc50 = $lub->visc(50);

    # Viscosity index (VI)
    my $vi = $lub->vi;

    # Viscosity-temperature constant:
    my $vtc = $lub->vtc;

    # m-value, aka V-T behavior coefficient
    my $m = $lub->m;

    # To draw the V-T (hyperbolic) graph of this particular lubricant we can generate data-points, say, from -20 to +100:

    my @data_points;
    for my $T(-20..100) {
        push @data_points, [$T, $lub->visc($T)];
    }

    # Now you may pass @data_points to either GDGrap(Perl) or Highcharts(JS).

=cut

use strict;
use warnings;
use Carp;

our $VERSION = '0.03';

=head2 new(\%attr)

Constructor. Following attributes (all optional) can be passed:

=over 4

=item label

Arbitrary label of the lubricant. Used in graph data or report tables, charts

=item visc40, visc100

Viscosity @ 40 and 100 degrees Celcius.

=item vi

Viscosity index of the lubricant.

=item density

Specific gravity of the lubricant at a given temperature point. Must be passed a hashref of Temprature-Density values. Density
must be in kg/cm3.

=back

B C and C are just convenience attributes, since they are most widely given in product TDSs.
If you don't have calibration points at these temperatures IGNORE these attributes. Instead,
create empty constructor, set the calibration values you already have using C method. Such as:

    my $lubricant = Tribology::Lubricant->new({label => "Hypothetical lubricant"});
    $lubricant->visc(50, 80);
    $lubricant->visc(100, 5.23);

=cut

sub new {
    my ( $class, $arg ) = @_;

    $arg ||= {};

    my %internals = (
        __visc_calibration_points => {},
        %$arg
    );

    if ( defined( $internals{visc40} ) ) {
        $internals{__visc_calibration_points}{40} = $internals{visc40};
    }

    if ( defined $internals{visc100} ) {
        $internals{__visc_calibration_points}{100} = $internals{visc100};
    }
    return bless( \%internals, $class );
}

=head2 label($new_label)

Returns and/or sets label of the lubricant

=cut

sub label {
    my ( $self, $new_label ) = @_;

    if ($new_label) {
        $self->{label} = $new_label;
    }
    return $self->{label};
}

=head2 visc($T, $cst)

Given temperature ($T) in celcius returns kinematic viscosity in cst. If such value was not given to the constructor it attempts to calculate
this number using B equation. For this to be possible at least two calibration points must be given to C or two calibration
points must be set using two-argument syntax of C.

If second argument is passed sets the viscosity point and returns the value $cst as is.

# 1.10 (eni), bo'yi ( 2.27 )

=cut

sub visc {
    my ( $self, $T, $cst ) = @_;

    unless ( defined $T ) {
        croak "visc(): usage error";
    }

    if ( defined $cst ) {
        $self->{__visc_calibration_points}{$T} = $cst;
        return $cst;
    }

    # If this calibration point was already given just return it:
    if ( my $visc = $self->{__visc_calibration_points}{$T} ) {
        return $visc;
    }

    # We have to attempt to calculate the viscosity at this given temp

    my @calibrations = @{ $self->__calibration_points(2) };
    unless ( scalar(@calibrations) == 2 ) {
        croak "visc(): Not enough calibration points to complete Ubbelohde-Walter equation";
    }

    my $c1_temp = $calibrations[0][0];
    my $c1_cst  = $calibrations[0][1];

    my $c2_temp = $calibrations[1][0];
    my $c2_cst  = $calibrations[1][1];

    my $vtc = $self->vtc;

    #my $b = ( log( log( $c1_cst + $vtc ) ) - log( log( $c2_cst + $vtc ) ) ) / ( log($c2_temp) - log($c1_temp) );
    my $m = $self->m;
    my $a = log( log( $c2_cst + $vtc ) / log(10) ) / log(10) + ( $m * log($c2_temp) / log(10) );

    #carp "\$c2_cst = $c2_cst";
    #carp "\$c2_temp = $c2_temp";
    #carp "\$a = $a";
    #carp "\$m = $m";
    #carp "\$vtc = $vtc";

    my $c = $a * 100;
    my $d = $m * 25;

    my $visc = exp(1)**( log(10) * exp(1)**( ( ( $c * log(10) ) / 100 ) - ( ( $d * log( __c2k($T) ) ) / 25 ) ) ) - 0.7;

    $self->{__visc_calibration_points}{$T} = $visc;
    return $visc;
} ## end sub visc

=head2 m()

Heart of the B equation. This is the coeffient that characterises V-T behavior of oils. It's a double-logarithmic V-T graph slope.
It requires at least two calibration points be present, or must be calculatable to work. Otherwise it throws error (croaks).

=cut

sub m {
    my $self = shift;

    my $calibrations = $self->__calibration_points(2);

    unless ( scalar @$calibrations == 2 ) {
        croak "m(): at least 2 calibration points are required to properly calculate V-T slope (m).";
    }

    my $c1_temp = $calibrations->[0][0];
    my $c1_cst  = $calibrations->[0][1];

    my $c2_temp = $calibrations->[1][0];
    my $c2_cst  = $calibrations->[1][1];

    #carp "c1_temp = $c1_temp\nc1_cst=$c1_cst\n";
    #carp "c2_temp = $c2_temp\nc2_cst=$c2_cst\n";

    my $vtc = $self->vtc;
    return ( log( log( $c1_cst + $vtc ) ) - log( log( $c2_cst + $vtc ) ) ) / ( log($c2_temp) - log($c1_temp) ) ;
}

=head2 LH()

Returns B and B values for the given lubricant. For this method to work lubricant's viscosity @ 100C must be known or calculatable.

=cut

sub LH {
    my ($self) = @_;

    my $cst100 = $self->visc(100);
    unless ($cst100) {
        croak "__LH(): Viscosity of the lubricant \@ 100C is unknown. Cannot proceed further";
    }

    if ( $cst100 < 2 ) {
        croak "__LH(): ASTM D2270 does not define VI for lubricants below 2cst \@ 100C";
    }

    if ( $cst100 > 70 ) {
        my $L = ( 0.8353 * ( $cst100**2 ) ) + 14.67 * $cst100 - 216;
        my $H = ( 0.1684 * ( $cst100**2 ) ) + 11.85 * $cst100 - 97;
        return ( $L, $H );
    }

    my ( @one_before, @one_after );
    seek( DATA, 0, 0 );
    while ( my $line =  ) {
        next unless length($line);
        next if $line =~ m/^#/;
        next if $line =~ m/^\s*$/;

        my ( $visc, $L, $H ) = $line =~ m/^
            ([\d\.]+) \s+ ([\d\.]+) \s+ ([\d\.]+)
        \s* $/x;

        next unless ( $visc && $L && $H );
        return ( $L, $H ) if ( $visc == $cst100 );
        if ( $visc < $cst100 ) {
            @one_before = ( $visc, $L, $H );
            next;
        }
        if ( $visc > $cst100 ) {
            push @one_after, $visc, $L, $H;
            last;
        }
    }

    unless ( @one_before && @one_after ) {
        croak "__LH(): has nothing to interoplate";
    }

    my $visc1      = $one_before[0];
    my $visc2      = $one_after[0];
    my $visc_delta = $visc2 - $visc1;

    my $L1      = $one_before[1];
    my $L2      = $one_after[1];
    my $L_delta = $L2 - $L1;

    my $H1      = $one_before[2];
    my $H2      = $one_after[2];
    my $H_delta = $H2 - $H1;

    my $L1_per_unit = $L_delta / $visc_delta;
    my $H1_per_unit = $H_delta / $visc_delta;

    my $L = $L1 + ( ( $cst100 - $visc1 ) * $L1_per_unit );
    my $H = $H1 + ( ( $cst100 - $visc1 ) * $H1_per_unit );

    return ( $L, $H );
} ## end sub LH


sub data_table {
    my $self = shift;

    my @data = ();
    seek( DATA, 0, 0 );
    while ( my $line =  ) {
        next unless length($line);
        next if $line =~ m/^#/;
        next if $line =~ m/^\s*$/;

        my ( $visc, $L, $H ) = $line =~ m/^
            ([\d\.]+) \s+ ([\d\.]+) \s+ ([\d\.]+)
        \s* $/x;

        next unless ( $visc && $L && $H );

        push @data, [$visc, $L, $H];
    }
    return \@data;
}

=head2 vi()

Returns viscosity index of the lubricant, if such is possible. Remember, for this to be possible
calibration points at 40C and 100C must be available or calculatble. If it's impossible, it returns undef and writes a warning
to STDERR. When checking for error you must check for C at return.

=cut

sub vi {
    my ($self) = @_;

    my $vi = $self->__vi_lt_100;
    if ( $vi > 100 ) {
        $vi = $self->__vi_gt_100;
    }
    return $vi;
}

sub log10 {
    my ($n) = @_;
    return ( log($n) / log(10) );
}

=head2 vtc()

Returns B used in B equation to better differentiate V-T behavior
when the influence of temperature is low. This constant must be used to accurately (or properly) calculate C.
To calculate this value properly we need to have calibration points at 40C and 100C. If either of these points are missing
C defaults to 0.8.

=cut

sub vtc {
    my $self = shift;

    my $visc40  = $self->{__visc_calibration_points}{40};
    my $visc100 = $self->{__visc_calibration_points}{100};

    return 0.8 unless ( $visc40 && $visc100 );
    return ( $visc40 - $visc100 ) / $visc40 ;
}

=head2 is_mineral

Based on the C constant or C attempts to guess if current instance represents a mineral oil.

=cut

sub is_mineral {
    my $self = shift;
    my $vi   = $self->vi;
    die "work in progress";
}

=head1 INTERNALS

=head2 __c2k($T)

Given temperature in celcius converts it to Kelvin

=cut

sub __c2k {
    my ($c) = @_;
    unless (defined $c) {
        die "__c2k(): usage error";
    }
    return ( $c + 273.15 );
}

=head2 __k2c($T)

Given temperature in Kelvin converts it to celcius

=cut

sub __k2c {
    my ($k) = @_;
    return ( $k - 273.15 );
}

=head2 __calibration_points($limit)

Returns all known calibration points to the lubricant as array reference. If C<$limit> is given limits the result set to that many points.
The points are guaranteed to be in ascending order by temperature. All temperature points are converted to Kelvin, since that's
what all internal formulas rely on.

=cut

sub __calibration_points {
    my ( $self, $limit ) = @_;

    my @calibrations = ( sort { $a <=> $b } keys %{ $self->{__visc_calibration_points} } );

    my $lowest_temp  = $calibrations[0];
    my $highest_temp = $calibrations[-1];

    return [
        [ __c2k($lowest_temp),  $self->visc($lowest_temp) ],
        [ __c2k($highest_temp), $self->visc($highest_temp) ]
    ];
}

=head2 __vi_lt_100()

Uses algorithm described in B<5. Procedure A> section of ASTM D2270. When you use C it invokes  either method
accordingly.

=cut

sub __vi_lt_100 {
    my ($self) = @_;

    my $cst40  = $self->visc(40);
    my $cst100 = $self->visc(100);

    unless ( $cst40 && $cst100 ) {
        croak "vi2(): viscosities at 40C and 100C must be known or calculatable";
    }

    my ( $L, $H ) = $self->LH;
    my $vi = ( ( $L - $cst40 ) / ( $L - $H ) ) * 100;

    return sprintf( "%d", $vi );
}

=head2 __vi_gt_100()

Uses algorithm described in B<6. Procedure B> section of ASTM D2270. When you use C it invokes either method
accordingly.

=cut

sub __vi_gt_100 {
    my ($self) = @_;

    my ( undef, $H ) = $self->LH;
    my $cst40  = $self->visc(40);
    my $cst100 = $self->visc(100);

    my $N = ( log10($H) - log10($cst40) ) / log10($cst100);
    my $vi = ( ( ( 10**$N ) - 1 ) / 0.00715 ) + 100;
    return sprintf( "%d", $vi );
}

=head1 SEE ALSO

L, Second Edition by  Wiley-VCH

=cut

1;

__DATA__