Documentation for gnumpy

Manual

• Example: arrays of integers.
• As a consequence, your code will have to deal with two types of arrays.
• To facilitate this, gnumpy includes many simple functions that work on both types of arrays.
• Operations over a specific dimension, or over the entire array: sum, mean, max, min, prod, std
• Elementwise operations: exp, log, logistic, sqrt, sign, isnan, isinf, log10
• When given a garray, they return a garray.
• When given a numpy array, they return a numpy array.
• The elementwise ones, when given a number, return a floating point number.

• Consider these statements: "from numpy import *; A = garray(range(12)); B = log(2)*A"
• Now, probably unexpectedly and undesirably, B is a numpy array.
  • The imported numpy.log() is a numpy procedure. It returns values not of type float, but of type numpy.float64 (though they don't look different).
  • If you multiply a value of type numpy.float64 with a garray, numpy quietly does type casting and transforms the garray into a numpy array.
• To prevent this from happening without your knowledge, gnumpy refuses such implicit conversions.
  • If you want to, you can change that behavior by setting the system environment variable GNUMPY_IMPLICIT_CONVERSION to 'allow' or 'warn'.
    • If you want to allow it but see a warning if it happens, set that variable to 'warn'.
    • If you want to allow such quiet conversions without a warning being shown, set it to 'allow'.
    • If you don't set the variable at all, or set it to 'refuse', these implicit conversions will raise an exception.
  • The quiet conversion to numpy arrays works by calling the __array__() method. That method will act according to the instruction in GNUMPY_IMPLICIT_CONVERSION
• If you want to convert a garray to a numpy array, you can always do it explicitly, using .as_numpy_array()

• The function gnumpy.memory_in_use() will tell you how much GPU memory you're using.
• The function gnumpy.memory_allocators() can tell you which lines of your code caused a lot of memory allocation.
  • Before you can use this, you have to set gnumpy.track_memory_usage=True. This enables data collection, which in disabled by default because it takes quite some time.

• Gnumpy can do all of its work on the CPU, if you ask it to or if there is a problem with the gpu setup.
• The system environment variable GNUMPY_USE_GPU, if present, controls this behavior.
  • value 'auto', or this variable not existing, means that gnumpy runs on a gpu if the gpu setup works, but on the cpu if there's a problem with the gpu setup.
  • value 'yes' means that gnumpy runs on a gpu. If that doesn't work, it's an error.
  • value 'no' means that gnumpy runs on the cpu.
• When you run on the CPU, you can choose the numerical precision: 32 bit (i.e. same as the gpu), 64 bit (the typical cpu precision), or 128 bit (high precision).
  • Environment variable GNUMPY_CPU_PRECISION, if present, controls this behavior. Its value has to be one of 32 (default), 64, or 128.
• Running on the cpu, with st least 64 bit precision, may be necessary in order to do gradient checks with finite difference approximations.

• The standard implementation of the logistic function, "1 / (1 + (-x).exp())", is not very fast.
• There is a direct implementation that's faster: x.logistic() or gnumpy.logistic(x)

• This section is irrelevant if your machine has only one GPU board.
• The default way gnumpy chooses a board is by asking Iain Murray's gpu_lock to pick one.
  • If your system doesn't have gpu_lock installed, then gnumpy prints a warning and simply uses board #0.
• You can change this behavior by setting gnumpy.board_id_to_use after importing gnumpy and before creating any garray's.
  • You can set it to an integer to specify which board to use.
  • Alternatively, you can set it to a function (which takes no arguments). That function will be called when you first create a garray, and it is expected to return an integer: the board id to use.

• Gnumpy does lots of error checking. Some of those checks, however, can take up quite a bit of time.
• You can tell gnumpy whether or not to perform the most time-consuming checks.
• The variable gnumpy.expensive_check_probability can be set to 0 (never check), 1 (always check), or anything in between (check randomly, with that probability).
• By default, its value is 1 (i.e. all checks are always performed).

• If you want gnumpy to check whether any nans or infs are created, set gnumpy.acceptable_number_types to "no nans" or to "no nans or infs".
• This way, gnumpy will check the result of most operations, and if it finds undesirable values, it raises a GnumpyNumberTypeException.
• If you want to disable the checks, restore gnumpy.acceptable_number_types to its default value, which is "anything goes".
• To specify in more detail what to check, there's gnumpy.dont_check_number_types_in_non_garrays, which by default is set to True.

• It's only when you're creating a numpy array from a *tuple* of arrays.
• The reason is that numpy array construction from tuples uses a loop to get the elements from the arrays.
• If you know where in your code this is happening, I suggest that you instead create a garray from that tuple of arrays. That is fast. If you want a numpy array, you can get one from that garray using .as_numpy_array()

Differences from numpy ndarrays

• Thus, if you edit the data in the alias, you're also editing the data in the original, and vice versa.
• Examples of aliasing operations: transpose, slice, reshape.

• Slicing (with step 1, i.e. using at most one colon), along the first dimension (in matrices that means selecting some complete rows). E.g. 'A[3:6]' or 'A[-1]'
• Reshaping
• Shallow copying, i.e. "garray(other_garray, copy=False)"
• Everything else, such as using A.T, makes a copy of the data.

• The syntactic difference is important.
• If the slicing operation is on the left side of an assignment statement, it's called slice assignment and it has nothing to do with aliasing.
• If the slicing operation is not on the left side of an assignment statement, it's called an expression and aliasing might be relevant.
• Example: "A[:,3] = B" works like in numpy, because it's slice assignment.
• Example: "temp=A[:,3]; temp[:]=B" does not work like in numpy, because it's a non-aliasing expression followed by an assignment.
• Example: "temp=A[3,:]; temp[:]=B" works like in numpy, because the expression is a row slice and therefore DOES alias, like in numpy.

• Even some tasks that a gpu could perform quickly might not be fast in gnumpy, if cudamat does not support them.

Differences from cudamat. Some features behave more like numpy.ndarray:

Execution speed

• Elementwise operations are fast on the gpu, especially if they don't involve division or more complicated operations like cosine
• Matrix multiplies are fast on a gpu, but there is some overhead in starting them up, so multiplying 5x5 matrices is probably faster on the cpu.