The acol Command Line Utility¶

acol contents¶

acol introduction
acol functions
acol types
Value specifications
Vector specifications
String list specifications
Multiple vector specifications
acol Example

acol introduction¶

O₂scl contains a command line utility, c 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 O₂scl objects of type table, hist, table3d, hist_2d, tensor_grid 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 O₂scl.

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.

acol functions¶

Some acol commands can work with mathematical function arguments. Functions can be created using the operators and functions listed below. Examples are x==5 && y<1, acos(-1), and sin(x>5). Comparison operators result in either 1.0 (true) or 0.0 (false).

Operators: () ^ * / % + - == != < > && || << >> >= <=

Functions: exp(x) log(x) log10(x) sin(x) cos(x) tan(x) sqrt(x) abs(x) asin(x) acos(x) atan(x) sinh(x) cosh(x) tanh(x) asinh(x) acosh(x) atanh(x) floor(x)

There is also a command called function which works with several different types to generate data based on functions. Use acol -help function to get more information on these type-specific commands.

acol types¶

The types which can be handled by acol are either related to C++ internal types: char, double, double[], int, int[], size_t, size_t[], std::string, and std::string[], or O₂scl types hist, hist_2d, prob_dens_mdim_amr, table, table3d, tensor (including double, int, and size_t versions), tensor_grid uniform_grid, and vector<contour_line>.

Value specifications¶

Some acol commands take “value specifications” as arguments, which are string expressions which represent a fixed numerical value. These specifications are handled by o2scl_hdf::value_spec(). The first part of the specification is a “type of specification” followed by a colon, followed by arguments which depend on the type. If no colon is present, then a “func:” prefix is assumed. The different types for a value specification are:

1. <numeric value or function> - Value equal to the result of <function>, e.g. “7.6” or “sin(0.5)”. See acol functions for a list of functions that can be used.

2. hdf5:<object name>:[addl. spec.] - Read an HDF5 value and obtain the value from object named <object name>. For some object types, additional specifications are required to specify which value should be used. A list of object types and additional specifications and more detail is given below.

Type	Additional specification	Description
double	(none)
int	(none)
size_t	(none)
double[]	index
int[]	index
size_t[]	index
uniform_grid<double>	index
table	column name, row index

3. shell:<shell command> - Set the value equal to the first result obtained using the specified shell command.

Vector specifications¶

Some acol commands take “value specifications” as arguments, which are string expressions which represent a list of numerical values. These specifications are handled by o2scl_hdf::vector_spec(). The different parts of the string are separated by a colon, and the first part specifes the type of vector specification. The different types are:

1. val:<value> - Create a vector with one element equal to <value>, which may be a number or a simple function, e.g. val:sin(0.5).

2. list:<entry 0>,<entry 1>, ..., <entry n-1> - Create a vector with a simple list of numbers or functions, e.g. ‘list:3.0,1.0e-3,sqrt(2.0)’.

3. func:<N>:<function of i> - Create a vector by specifying the length of the vector and a function used to fill the elements. For example: ‘func:41:sin(i/20.0*acos(-1))’.

4. grid:<begin>,<end>,<width>,["log"] - Create a vector equal to a uniform grid, e.g. use ‘grid:1.0,10.0,1.0’ for a 10-element vector filled with the numbers 1 to 10.

5. text:<filename>:<column index> - Read a text file and extract a vector of numbers from a column of the text file (starting with zero for the first column), ignoring any header rows which contain non-numeric values. For example ‘text:~/temp.dat:2’ will construct a vector from the third column of the file ‘temp.dat’ in the user’s home directory (using wordexp_single_file() which calls the system wordexp() function to expand the tilde).

6. hdf5:<file name>:<object name>:[addtional spec.] - Read an HDF5 file and obtain a vector from the object with the specified name. The remaining parts of the string contain additional information which may be needed depending on the type of object stored in the HDF5 file. A list of object types and additional specifications and more detail is given below.

Type	Additional specification	Description
double	(none)	Implies vector of size 1
double[]	(none)
hist	(none)	Vector of histogram weights
int	(none)	Implies vector of size 1
int[]	(none)
size_t	(none)	Implies vector of size 1
size_t[]	(none)
table	<column>	Selected column from table
table	<row> <col pat>	Selected row and columns
uniform_grid<double>	(none)

For table <row> <col pat>, the first additional specification is a row number, which can be negative to refer to counting from the end of the table. The second additional specification is a pattern of column names using either ‘*’ or ‘?’.

String list specifications¶

Some acol commands take “string list specifications” as arguments, which are string expressions which represent a list of strings. These specifications are handled by o2scl_hdf::strings_spec(). The different parts of the string are separated by a colon, and the first part specifes the type of vector specification. The different types are:

list:<comma-separated list> - A list of strings

2. shell:<command> - The lines obtained from the result of a shell command, with a maximum of 256 characters per line.

3. pattern:N:x[0][a][A] - The N strings obtained from a pattern. Occurrences of [0] are replaced with the integer ‘i’ where i runs from 0 to N-1. Occurrences of [a] are replaced with ‘a’ through ‘z’ from 0 through 25, and ‘aa’ through ‘zz’ for i from 26 to 701. Occurrences of [A] are replaced with ‘A’ through ‘Z’ from 0 through 25, and ‘AA’ through ‘ZZ’ for i from 26 to 701.

hdf5: - Unfinished.

Multiple vector specifications¶

Some acol commands take “multiple vector specifications” as arguments, which are string expressions which represent a list of vectors (which need not have the same length). These specifications are handled by o2scl_hdf::mult_vector_spec(). The different parts of the string are separated by a colon, and the first part specifes the type of multiple vector specification. The different types are:

1. func:<N>:<function of i>:<function of i and j> - Specify the number of vectors, a function of “i” which determines the length of the ith vector, and a function of “i” and “j” which specifies the jth element of the ith vector.

2. text:<filename pattern>:<numeric column list> - Read one or more text files and extract vectors of numbers from columns of the text file, ignoring any header rows which contain non-numeric values. For example ‘text:~/temp.dat:2-4’ will construct vectors from the third, fourth, and fifth columns of the file ‘temp.dat’ in the user’s home directory.

3. hdf5:<filename pattern>:<object name>:[additional spec.] - Read one or more HDF5 files and obtain a vector from the object with the specified name. The remaining parts of the string contain additional information which may be needed depending on the type of object stored in the HDF5 file.

Type	Additional specification	Description
table	<column pattern>

Also, many normal vector specifications (from ‘acol -help vector-spec’) also work as multiple vector specifications. These include specifications which begin with ‘val:’, ‘list:’, ‘grid:’, and ‘table-row:’. Also included are ‘hdf5:’ specifications which refer to objects of type double, double[], hist, int, int[], size_t, size_t[], and uniform_grid<double>.

acol Example¶

#
# -----------------------------------------------------------------
# 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> <val> : For types [35m[1mchar[m, [35m[1mint[m, [35m[1msize_t[m, and [35m[1mstring[m, create an object and give it the initial value specified.

create double <value spec.> : Create a [35m[1mdouble[m object and set it equal to the value specified by <value spec.>. (See "acol -help <tt>functions</tt>' for help on specifying
functions and "acol -help value-spec" for help on value
specifications.)

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

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

<tt>create table <name> <vector spec.></tt>:
Create a new <tt>table</tt> object with one column named <name>
from a vector specification (see <tt>Vector specifications</tt>
for the syntax).

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

<tt>create tensor_grid <rank> <size 0> <size 1>...</tt>:
Create a <tt>tensor_grid</tt> 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 <tt>set-grid</tt>.

<tt>create table3d <x name> <x vector spec.> <y name> <y
vector spec.>\n <slice name> <slice function></tt>: Create a
new <tt>table3d</tt> 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.

For example, using <tt>o2graph</tt> from o2sclpy:

<tt>o2graph -create table3d x func:100:i/200 y func:100:i/200
z "sin(1/(x+0.01))* sin(1/(y+0.01))" -den-plot z -xtitle x -ytitle y -show 
# -----------------------------------------------------------------
# The full command list is given with 'commands'
# -----------------------------------------------------------------
> commands
No current object.

Commands which do not require a current object:

alias       convert     generic     license     read        version     
autocorr    create      get         ninteg      run         warranty    
calc        docs        h5-copy     no-intro    set         wdocs       
clear       download    help        output      shell       xml-to-o2   
commands    exit        interactive preview     slack       
constant    filelist    internal    quit        type        

Use '-commands all' for a list of all commands for the various types.
# -----------------------------------------------------------------
# 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
Set interpolation type to linear interpolation (1).
> 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
Set interpolation type to linear interpolation (1).
# -----------------------------------------------------------------
# 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
Number of columns: 0
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).