NAME

Physics::Unit::Scalar

SYNOPSIS

    # Distances
    $d = new Physics::Unit::Distance('98 mi');
    print $d->ToString, "\n";             # prints 157715.712 meter
    $d->add('10 km');
    print $d->ToString, "\n";  # prints 167715.712 meter
    print $d->value, ' ', $d->default_unit->name, "\n";   # same thing
    # Convert
    print $d->ToString('mile'), "\n";        # prints 104.213... mile
    print $d->convert('mile'), " miles\n";   # same thing (except 'miles')
    $d2 = new Physics::Unit::Distance('2000');   # no unit given, use the default
    print $d2->ToString, "\n";                   # prints 2000 meter
    # Times
    $t = Physics::Unit::Time->new('36 hours');
    print $t->ToString, "\n";              # prints 129600 second
    # Speed = Distance / Time
    $s = $d->divide($t);            # $s is a Physics::Unit::Speed object
    print $s->ToString, "\n";    # prints 1.2941... mps
    # Automatic typing
    $s = new Physics::Unit::Scalar('kg m s');   # Unrecognized type
    print ref $s, "\n";          # $s is a Physics::Unit::Scalar
    $f = $s->divide('3000 s^3');
    print ref $f, "\n";          # $f is a Physics::Unit::Force

DESCRIPTION

This package encapsulates information about physical quantities. Each instance of a class that derives from Physics::Unit::Scalar holds the value of some type of measurable quantity. When you use this module, several new classes are immediately available. See the UnitsByType page for a list of types included with the unit library.

You will probably only need to use the classes that derive from Physics::Unit::Scalar, such as Physics::Unit::Distance, Physics::Unit::Speed, etc. You can also define your own derived classes, based on types of physical quantities.

This module relies heavily on Physics::Unit. Each Scalar object references a Unit object that defines the dimensionality of the Scalar. The dimensionality also identifies (usually) the type of physical quantity that is stored, and the derived class of the object.

For example, the class Physics::Unit::Distance uses the Physics::Unit object named 'meter' to define the scale of its object instances. The type of the 'meter' object is 'Distance'.

Defining classes that correspond to physical quantity types allows us to overload the arithmetic methods to produce derived classes of the correct type automatically. For example:

  $d = new Physics::Unit::Distance('98 mi');
  $t = new Physics::Unit::Time('36 years');
  # $s will be of type Physics::Unit::Speed.
  $s = $d->divide($t);

When a new object is created, this package attempts to determine its subclass based on its dimensionality. Thus, when you multiply two Distances together, the result is an Area object. This behavior can be selectively overridden when necessary. For example, both energy and torque have the same dimensions, Force * Distance. Therefore, it remains the programmer's responsibility, in this case, to assign the correct subclass to Scalars that have this dimensionality.

See also the Physics::Unit::Scalar::Implementation page for more details.

EXPORT OPTIONS

By default, this module exports nothing. You can request all of the functions to be exported as follows:

  use Physics::Unit::Scalar ':ALL';

Or, you can just get specific ones. For example:

  use Physics::Unit::Scalar qw( ScalarFactory GetScalar );

FUNCTIONS

ScalarFactory($type): Creates a new object of one of the subtypes of Scalar, from an expression. The syntax of the expression is the same as the unit expression used by the Physics::Unit module.
The class of the resultant object matches the type of the unit created. If the type is not recognized or ambiguous, then the class of the resultant object will be Physics::Unit::Scalar.
GetScalar($arg): This convenience function takes an object reference or an expression, and returns a Physics::Unit::Scalar object. If $arg is an object reference, it is simply returned.

METHODS

CLASS->new([$value])

$s->new()

Package or object method. This makes a new user defined Scalar (or derived class) object. For example:

    # This creates an object of a derived class
    $d = new Physics::Unit::Distance('3 miles');
    # This does the same thing; the type is figured out automatically
    # $d will be a Physics::Unit::Distance
    $d = new Physics::Unit::Scalar('3 miles');
    # Use the default unit for the subtype (for Distance, it's meters):
    $d = new Physics::Unit::Distance(10);
    # This defaults to one meter:
    $d = new Physics::Unit::Distance;
    # Copy constructor:
    $d2 = $d->new;

If the type cannot be identified by the dimensionality of the unit, then a Physics::Unit::Scalar object is returned.

$s->ToString([$unit])

Returns a string representation of the scalar, either in the default units or the unit specified.

$s->default_unit()

Get the default unit object which is used when printing out the given Scalar.

$s->convert($unit)

Returns the numerical value of this scalar expressed in the given Unit.

$s->value([$newValue])

Get or set the value.

$s->add($v)

Add another Scalar to the provided one.

$s->neg($v)

Take the negative of the Scalar

$s->subtract($v)

Subtract another Scalar from this one.

$s->times($v)

This returns a new object which is the product of $self and the argument. Neither the original object nor the argument is changed.

[FIXME: see Github issue #22. These methods should all work the same way. Either all change the value of the existing object, or all return a new object.]

$s->recip($v)

Returns a new Scalar object which is the reciprocal of the object. The original object is unchanged.

$s->divide($v)

This returns a new Scalar object which is a quotient. Neither the original object nor the argument is changed.

OVERLOADED OPERATORS

These operators/functions are overloaded: +, -, *, /, **, int, abs, exp, log, sin, cos, atan2, <=>, eq, ne, "", 0+ and bool.

As mentioned above, it is possible to units to be indeterminate from their dimensions alone, for example, energy and torque have the same dimensions. For cases where this ambiguity might arise during use of the overloaded interface, a package variable @type_context has been provided so the user can specify. It's not a requirement, but it's possible an inappropriate unit might appear if this variable is not set up.

To facilitate output when producing a string representation, the $format_string package variable can be given a sprintf-compatible format string to e.g. restrict the number of decimal places.

The following example illustrates usage of the overloaded interface and the variables described above.

    # simple projectile motion simulation on different planets
    use Physics::Unit::Scalar ':ALL';
    @Physics::Unit::Scalar::type_context = ('Energy');      # we are working with energy i.e. Joules
    $Physics::Unit::Scalar::format_string = "%.3f";         # provide a format string for output
    my $m = GetScalar("1 Kg");                              # mass
    my $u = GetScalar("1 meter per second");                # initial upward velocity
    foreach my $body ( qw(mercury earth mars jupiter pluto) ) {
        my $a = GetScalar("-1 $body-gravity");              # e.g. "-1 earth-gravity" (-1 for direction vector)
        my $t = GetScalar("0 seconds");                     # start at t = 0s
        print "On " . ucfirst($body) . ":\n";               # so we know which planet we're on
        while ( $t < 3.5 ) {                                # simulate for a few seconds
            my $s = $u * $t + (1/2) * $a * $t**2;           # 'suvat' equations
            my $v = $u + $a * $t;
            my $KE = (1/2) * $m * $v**2;                    # kinetic energy
            my $PE = $m * -1 * $a * $s;                     # potential energy, again -1 for direction
            my $TE = $KE + $PE;                             # total energy (should be constant)
            # display with units
            print "At $t: dist = $s;\tvel = $v;\tKE = $KE;\tPE = $PE;\tTotal energy = $TE\n";
            $t += 0.1;                                      # increment timestep
        }
    }

AUTHOR

Chris Maloney <voldrani@gmail.com>