The 'acol' Command-line Utility

O2scl contains a command-line utility, acol, designed to facilitate the manipulation of various objects stored in HDF5 files. It can handle integers, characters, double-precision floating point numbers, size_t objects, arrays of any of these types, or O2scl objects of type o2scl::table, o2scl::hist, o2scl::table3d, o2scl::hist_2d, o2scl::tensor_grid and o2scl::contour_line .

acol can only operate with one object at a time. The basic workflow is:

  • create an object from scratch or read it from an HDF5 file
  • perform operations on that object
  • output the object to the screen or write it to an HDF5 file

The available command list can be obtained using 'help' or 'commands' and changes depending on what type of object is currently in memory. In order to list the commands which would be available given a particular type, give 'commands' the type as an argument, i.e. acol -commands table . In order to get detailed help on how a command operates on a particular type, give the type and the command as arguments to help, e.g. acol -help table interp. There are some commands which are available for all types, and obtaining the help information for these commands does not require a type argument, i.e. acol -commands or acol -help read.

acol can sometimes, but not always read and write HDF5 files generated outside of O2scl .

acol has a command, run, which allows you to run a set of commands which are given in a separate file. An example script in the extras directory of the documentation is named acol.scr. The associated output is a useful demonstration of the capabilities of acol.

#
# -----------------------------------------------------------------
# This file documents the use of the 'acol' command. The command
# 'help' provides the full help text. You can also get help on the
# commands individually, e.g.
# -----------------------------------------------------------------
> help create
Usage: create <type> [...]

Short description: Create an object.

Long description:
Create a new object of type <type>. If an object is currently in memory, it is
deallocated before creating the new object.

"create <type> <value>": For types char, int, size_t, and string, create an
object and give it the initial value specified.

"create double <value-spec>": Create a double object and set it equal to the
value specified by <value-spec>. (See "acol -help functions" for help on
specifying functions.)

"create <type> <size> <function of "i">": For array types int[] and size_t[],
the user must specify the size of the array and a function of the array index
'i' to fill the array.

"create double[] [<size> <function of "i">] or [vector spec.]": For double[]
the user must either give a vector specification, or specify the size of the
array and a function of the array index 'i'.

"create table <name> <vector spec.>": Create a new table object with one
column named <name> from a vector specification (see "acol -help vector-spec"
for the syntax).

"create tensor <rank> <size 0> <size 1> ...": Create a tensor object with the
specified rank and sizes. All tensor entries are initialized to zero.

"create tensor_grid <rank> <size 0> <size 1> ...": Create a tensor_grid object
with the specified rank and sizes. The tensor grid is initialized to count
each index (beginning with zero) and the entries of the tensor are initialized
to zero. The grid can be specified afterwards using "set-grid".

"create table3d <x name> <x vector spec.> <y name> <y vector spec.>
<slice name> <slice function>": Create a new table3d object which has one
slice. The x and y grids are given as vector specifications (see "acol -help
vector-spec" for the syntax). The slice function can be written in terms of
the x- and y-grid values which are referred to by name.

# -----------------------------------------------------------------
# The full command list is given with 'commands'
# -----------------------------------------------------------------
> commands
Command list:

alias       create      get         license     read        slack       
autocorr    download    get-conv    no-intro    run         type        
calc        exit        help        output      set         version     
clear       filelist    interactive preview     shell       warranty    
commands    generic     internal    quit        show-units  

# -----------------------------------------------------------------
# Use 'create' to create a table with one column
# -----------------------------------------------------------------
> create table x grid:0,1,0.1
# -----------------------------------------------------------------
# Use 'function' to apply a function to create a new column
# -----------------------------------------------------------------
> function sin(x) s
> function sqrt(1-s*s) c
# -----------------------------------------------------------------
# The 'deriv' command computes derivatives
# -----------------------------------------------------------------
> deriv x s c2
# -----------------------------------------------------------------
# Use 'output' to see the results
# -----------------------------------------------------------------
> output
 x             s             c             c2           
 0.000000e+00  0.000000e+00  1.000000e+00  9.999995e-01 
 1.000000e-01  9.983342e-02  9.950042e-01  9.950034e-01 
 2.000000e-01  1.986693e-01  9.800666e-01  9.800667e-01 
 3.000000e-01  2.955202e-01  9.553365e-01  9.553335e-01 
 4.000000e-01  3.894183e-01  9.210610e-01  9.210695e-01 
 5.000000e-01  4.794255e-01  8.775826e-01  8.775485e-01 
 6.000000e-01  5.646425e-01  8.253356e-01  8.254605e-01 
 7.000000e-01  6.442177e-01  7.648422e-01  7.643741e-01 
 8.000000e-01  7.173561e-01  6.967067e-01  6.984518e-01 
 9.000000e-01  7.833269e-01  6.216100e-01  6.150954e-01 
 1.000000e+00  8.414710e-01  5.403023e-01  5.646134e-01 
# -----------------------------------------------------------------
# Or give 'output' command an argument to output to a file
# -----------------------------------------------------------------
> output test.txt
# -----------------------------------------------------------------
# Change the output precision using set
# -----------------------------------------------------------------
> set precision 4
> output
 x           s           c           c2         
 0.0000e+00  0.0000e+00  1.0000e+00  1.0000e+00 
 1.0000e-01  9.9833e-02  9.9500e-01  9.9500e-01 
 2.0000e-01  1.9867e-01  9.8007e-01  9.8007e-01 
 3.0000e-01  2.9552e-01  9.5534e-01  9.5533e-01 
 4.0000e-01  3.8942e-01  9.2106e-01  9.2107e-01 
 5.0000e-01  4.7943e-01  8.7758e-01  8.7755e-01 
 6.0000e-01  5.6464e-01  8.2534e-01  8.2546e-01 
 7.0000e-01  6.4422e-01  7.6484e-01  7.6437e-01 
 8.0000e-01  7.1736e-01  6.9671e-01  6.9845e-01 
 9.0000e-01  7.8333e-01  6.2161e-01  6.1510e-01 
 1.0000e+00  8.4147e-01  5.4030e-01  5.6461e-01 
> set precision 6
# -----------------------------------------------------------------
# Shell commands are proceeded by an '!'
# -----------------------------------------------------------------
> !cat test.txt
acol: Executing system command: cat test.txt
 x             s             c             c2           
 0.000000e+00  0.000000e+00  1.000000e+00  9.999995e-01 
 1.000000e-01  9.983342e-02  9.950042e-01  9.950034e-01 
 2.000000e-01  1.986693e-01  9.800666e-01  9.800667e-01 
 3.000000e-01  2.955202e-01  9.553365e-01  9.553335e-01 
 4.000000e-01  3.894183e-01  9.210610e-01  9.210695e-01 
 5.000000e-01  4.794255e-01  8.775826e-01  8.775485e-01 
 6.000000e-01  5.646425e-01  8.253356e-01  8.254605e-01 
 7.000000e-01  6.442177e-01  7.648422e-01  7.643741e-01 
 8.000000e-01  7.173561e-01  6.967067e-01  6.984518e-01 
 9.000000e-01  7.833269e-01  6.216100e-01  6.150954e-01 
 1.000000e+00  8.414710e-01  5.403023e-01  5.646134e-01 
acol: Done with system command (returned 0).
# -----------------------------------------------------------------
# Or store the results in the internal format 
# -----------------------------------------------------------------
> internal test.o2
# -----------------------------------------------------------------
# Generic text files can be read using the 'generic' command
# -----------------------------------------------------------------
> generic table test.txt
> output
 x             s             c             c2           
 0.000000e+00  0.000000e+00  1.000000e+00  9.999995e-01 
 1.000000e-01  9.983342e-02  9.950042e-01  9.950034e-01 
 2.000000e-01  1.986693e-01  9.800666e-01  9.800667e-01 
 3.000000e-01  2.955202e-01  9.553365e-01  9.553335e-01 
 4.000000e-01  3.894183e-01  9.210610e-01  9.210695e-01 
 5.000000e-01  4.794255e-01  8.775826e-01  8.775485e-01 
 6.000000e-01  5.646425e-01  8.253356e-01  8.254605e-01 
 7.000000e-01  6.442177e-01  7.648422e-01  7.643741e-01 
 8.000000e-01  7.173561e-01  6.967067e-01  6.984518e-01 
 9.000000e-01  7.833269e-01  6.216100e-01  6.150954e-01 
 1.000000e+00  8.414710e-01  5.403023e-01  5.646134e-01 
# -----------------------------------------------------------------
# Files in the internal format can be read with 'read'
# -----------------------------------------------------------------
> read test.o2
No name specified, found first table object named 'acol'.
> output
 x             s             c             c2           
 0.000000e+00  0.000000e+00  1.000000e+00  9.999995e-01 
 1.000000e-01  9.983342e-02  9.950042e-01  9.950034e-01 
 2.000000e-01  1.986693e-01  9.800666e-01  9.800667e-01 
 3.000000e-01  2.955202e-01  9.553365e-01  9.553335e-01 
 4.000000e-01  3.894183e-01  9.210610e-01  9.210695e-01 
 5.000000e-01  4.794255e-01  8.775826e-01  8.775485e-01 
 6.000000e-01  5.646425e-01  8.253356e-01  8.254605e-01 
 7.000000e-01  6.442177e-01  7.648422e-01  7.643741e-01 
 8.000000e-01  7.173561e-01  6.967067e-01  6.984518e-01 
 9.000000e-01  7.833269e-01  6.216100e-01  6.150954e-01 
 1.000000e+00  8.414710e-01  5.403023e-01  5.646134e-01 
# -----------------------------------------------------------------
# Tables also contain constant values in addition to data
# -----------------------------------------------------------------
> assign pi acos(-1.0)
# -----------------------------------------------------------------
# The 'list' command lists the column and constant names
# -----------------------------------------------------------------
> list
table name: acol
1 constant:
pi 3.141593e+00
4 columns: 
0. x  1. s  2. c  3. c2 
11 lines of data.
# -----------------------------------------------------------------
# Constants can be used in expressions
# -----------------------------------------------------------------
> function x*pi/2 x2
# -----------------------------------------------------------------
# Columns can be renamed. 
# -----------------------------------------------------------------
> rename x2 x_2
> output
 x             s             c             c2            x_2          
 []            []            []            []            []           
 0.000000e+00  0.000000e+00  1.000000e+00  9.999995e-01  0.000000e+00 
 1.000000e-01  9.983342e-02  9.950042e-01  9.950034e-01  1.570796e-01 
 2.000000e-01  1.986693e-01  9.800666e-01  9.800667e-01  3.141593e-01 
 3.000000e-01  2.955202e-01  9.553365e-01  9.553335e-01  4.712389e-01 
 4.000000e-01  3.894183e-01  9.210610e-01  9.210695e-01  6.283185e-01 
 5.000000e-01  4.794255e-01  8.775826e-01  8.775485e-01  7.853982e-01 
 6.000000e-01  5.646425e-01  8.253356e-01  8.254605e-01  9.424778e-01 
 7.000000e-01  6.442177e-01  7.648422e-01  7.643741e-01  1.099557e+00 
 8.000000e-01  7.173561e-01  6.967067e-01  6.984518e-01  1.256637e+00 
 9.000000e-01  7.833269e-01  6.216100e-01  6.150954e-01  1.413717e+00 
 1.000000e+00  8.414710e-01  5.403023e-01  5.646134e-01  1.570796e+00 
# -----------------------------------------------------------------
# (Remove test files created earlier.)
# -----------------------------------------------------------------
> !rm test.txt
acol: Executing system command: rm test.txt
acol: Done with system command (returned 0).
> !rm test.o2
acol: Executing system command: rm test.o2
acol: Done with system command (returned 0).

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).