vector command

The ::rbc::vector command creates and manages real or complex numeric vectors.

A vector can be accessed through:

  • its vector instance command

  • an associated Tcl array variable

  • the RBC C API.

Vector types

Each vector has an immutable numeric type:

  • real - the default type. Each vector value is a double-precision floating-point number.

  • complex - each vector value contains a double-precision real component and a double-precision imaginary component.

The type is selected when the vector is created:

::rbc::vector create x
::rbc::vector create z -type complex

The VECINST type operation returns the type of an existing vector.

Complex values are represented at the Tcl level as two-element lists:

{real imag}

For example:

::rbc::vector create z -type complex
z set {{1 2} {3 -4} {-2 0.5}}

z index 1
# -> 3.0 -4.0

A real scalar is also accepted where a complex value is expected and is promoted to a complex value with zero imaginary component. For example, 5 is equivalent to {5 0}.

A vector’s type cannot be changed after creation. Supplying -type for an existing vector is permitted only when the requested type is the same as its current type. Omitting -type when referring to an existing vector preserves its current type.

Real vectors retain the traditional automatic Tcl array mapping. Complex vectors do not receive an automatic array mapping, but one may be requested explicitly with -variable or later with VECINST variable.

Graph and spline integration

Complex vectors are supported directly by Polar graph elements and by parametric spline interpolation.

Traditional graph, barchart, and stripchart element data remain real-valued. A complex vector supplied to their ordinary X/Y data options is rejected rather than being implicitly converted to a real part, magnitude, or another projection.

A widget created by polar can attach a complex vector directly with the element -cdata option:

::rbc::vector create gamma -type complex
gamma set {{0 0} {0.2 0.4} {0.5 0.2}}

::rbc::polar .p -representation smith
.p element create trace -cdata gamma

Polar complex elements support three data formats:

gamma
impedance
admittance

selected with -cdataformat.

The scalar spline interface remains real-valued:

spline natural x y splX splY
spline quadratic x y splX splY

The parametric spline interface operates directly on complex vectors:

spline parametric natural source result samples
spline parametric quadratic source result samples

For example:

::rbc::vector create z -type complex
z set {{0 0} {1 1} {0 2} {-1 1}}

spline parametric natural z smoothZ 100

When a real projection of a complex vector is required for a traditional graph or scalar spline, it can be derived explicitly with expression functions such as real, imag, abs, or arg:

::rbc::vector create magnitude
magnitude expr {abs(z)}

Vector creation forms

Vectors may be created with an initially empty value array:

::rbc::vector create x

A size may be included in the vector specification:

::rbc::vector create x(100)

This creates a vector containing 100 values.

An explicit external index range may also be specified:

::rbc::vector create x(-5:14)

This creates 20 values and sets the vector index offset so that its externally visible indices run from -5 through 14.

The special name #auto requests an automatically generated vector name.

Vector names may be namespace-qualified.

Vector instances

The examples and command descriptions below use VECINST to denote the Tcl command associated with an individual vector.

For example:

set x [::rbc::vector create x]
$x seq 0 10 0.5
puts [$x length]

Copyright (c) George Yashin