Lua and CAS: Getting Started
In my previous blog we explored the steps required to configure Python to invoke CAS actions. Continuing the theme of exploring the open programmatic interfaces to CAS, this blog will review the steps required to install and configure Lua in preparation for submitting CAS actions to a CAS server.
Lua
Lua the programming language, not Lua the Hawaiian art of self-defense, dates back to the early 1990's when it was designed as a language for extending software applications to meet the increasing demand for customization. (The word "lua" means moon in Portuguese.) The Lua website describes the language as follows:
Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.
Lua combines simple procedural syntax with powerful data description constructs based on associative arrays and extensible semantics. Lua is dynamically typed, runs by interpreting bytecode with a register-based virtual machine, and has automatic memory management with incremental garbage collection, making it ideal for configuration, scripting, and rapid prototyping.
It's power and flexibility continue to make Lua one of the more popular open source languages available. As a result, it was chosen as one of the open languages to be supported by SAS Viya 3.1+. So let's look at what we need to get up and running with Lua and CAS.
Requirements
Of course the requirements are a good place to start. Listed below are the basic requirements in using Lua to interact with CAS:
- 64-bit Linux
- 64-bit Lua
- Lua 5.2+
- Lua packages - middleclass 4.0+, csv and ee5_base64
- SWAT (SAS Scripting Wrapper for Analytics Transfer) package
Architecture Basics
Since the first requirement is that Lua runs on 64-bit Linux, this obviously limits placement. Although Lua runs on Windows machines, interacting with a CAS server from Lua is only supported 64-bit Linux machines. One simple scenario places Lua users on the same machine as a VDMML deployment as shown in the following diagram.
Note that Lua, along with the required SAS client interface for Viya, are running on the same machine as SAS Studio, the SAS Object and CONNECT Spawners, SAS Workspace and CONNECT servers, and the CAS server and related components. One major benefit of running on the same machine is that communication between Lua and the CAS server takes place without having to cross the network. However, it does it at the expense of consuming resources on that machine, which may adversely impact the response times of SAS Studio and CAS actions.
An alternative deployment would place Lua and CAS client components on the same machine as SAS Studio, the SAS spawners and the Workspace and CONNECT servers. In this deployment the CAS server and related components run on a separate machine.
If machines are available for this configuration, this would allow an architect to isolate the CAS server and components. Of course this would eliminate the possibility of SAS Studio, Workspace and Lua workloads impacting the resource usage and response times of CAS actions as they are not sharing resources. Moving Lua to the machine where SAS Studio and Workspace and CONNECT servers reside ensures all resources on the CAS machine are dedicated to CAS workloads. One very minor downside to this configuration is that communication between the VDMML machine and the CAS server would require at least one hop in the network.
A third deployment option places Lua and CAS client components on a separate machine.
This architecture essentially isolates the various component groups on individual machines ensuring dedicated resources for the CAS server, VDMML components and Lua client. Like the previous configuration, isolating workloads essentially eliminates the potential resource impact of one workload on another.
The SSH client is one common component for all three configurations. This is the software used to logon to the Lua client machine and run Lua from the command line. In most instances this would be software such as MobaXterm running on a user's workstation.
Getting Started
Although 32-bit Linux installations appear to be going the way of dinosaurs, we first need to verify we are running on a 64-bit Linux machine. The uname command with the "-m" option displays this information. A value of x86_64 indicates 64-bit OS and values i686 and/or i386 are displayed for 32-bit.
Although the requirements list shown earlier is pretty straight-forward, chances are you may encounter the same issue I did upon diving into the steps. If you are working on a newly-minted OS, it is likely that the Lua version is one that is not supported. On my image the version was 5.1.4 on a RHEL 7.2 deployment.
An attempt to perform a "yum update lua" resulted in a minor revision update. A subsequent search of repositories did not return a supported version. In addition a search for a Lua RPM package returned no results. As a result it was necessary to build it from the source.
Building Lua from Source
In order to build binaries from source you will need a C compiler. This may or may not be available. If it is not available, install the C compiler. This process assumes the user is able to commands run as root.
yum install gcc
The readline-devel package is also required to compile Lua. The readline library provides a set of functions that allow users to edit typed command lines.
Now it is time to download Lua source files. The wget command can be used to retrieve them.
Next we unzip the zipped file
At this point all of the pieces should be in place to compile the source and generate the binaries. First change directory to the source files for Lua. In this example the zip file was saved in root's home directory. Then perform the compile using the install option (output of compile is not shown).
make linux install
The install option will store the executables and related files in subdirectories of /usr/local rather than /usr. If this directory does not exist, it will be created. The install option will then copy modules to the appropriate location. In addition, it will add the new location to the $PATH environment variable. If /usr/local did not exist before the compile/install, it may be necessary to restart your SSH session to set the environment variable with the new paths.
SWAT
The key ingredient that enables Lua to communicate with CAS is the SAS-provided Lua SWAT package. This package includes required Lua SWAT components, other required Lua packages and SAS TK modules.
If you are testing on the same machine as the SAS VDMML deployment, the required SWAT components should already be deployed. Those components can be found at /opt/sas/viya/home/SASFoundation/misc/casluaclnt/lua. It is just necessary to establish pathing to them before starting the Lua environment.
The following commands create the required environment variables when using Lua to talk to CAS. Notice the last environment variable TKPATH. This is the variable that defines the path to the SAS TK modules available with the VDMML installation.
export LUA_PATH="$LUA_PATH;$LUA_ROOT/?.lua"
export LUA_CPATH="$LUA_CPATH;$LUA_ROOT/lib/?.so"
export LUA_PATH="$LUA_PATH;$LUA_ROOT/deps/?.lua"
export TKPATH="/opt/sas/viya/home/SASFoundation/sasexe"
If the instance of Lua is running on a machine other than the VDMML deployment, then the SWAT package is required. First download the package from the SAS support web site. You will need a SAS profile to download the zipped package.
http://support.sas.com/downloads/package.htm?pid=1975
Unzip the package in the location of your choice. In the following example the swat package was extracted to /opt/sas. Once the zipped package has been extracted, set the required environment variables to the Lua SWAT path. Notice that the TKPATH environment variable is pointing to a subdirectory of the extract location.
export LUA_PATH="$LUA_PATH;$LUA_ROOT/?.lua"
export LUA_CPATH="$LUA_CPATH;$LUA_ROOT/lib/?.so"
export LUA_PATH="$LUA_PATH;$LUA_ROOT/deps/?.lua"
export TKPATH="$LUA_ROOT/tk"
The other Lua packages mentioned in the requirements section earlier are made available in SWAT package in the "deps" directories listed in the LUA_PATH environment variable.
Now Let's Test it
At this point all of the pieces should be in place to begin testing. We begin by starting the command line interface via the lua command. Once the command line is initiated, begin your program by loading the swat package. The next step is to establish a connection to the CAS server using the CAS method. In this connection statement credentials are supplied as part of the parameters. This is not a best practice. The .authinfo file should be used to specify credentials and the connection statement should point to it. Finally, to verify the connection use the "builtins" action set to verify the CAS server status.
s = swat.CAS("gatekrbhdp01", 5570, 'cas', '******')
results, info = s:builtins_serverStatus{}
print(results)
actions executed.> print(results)
Node Name Role Uptime (Sec) Running Stalled
pdcesx03044 controller 54.009 0 0
[About]
table: 0x256f3e0
[server]
Server Status
Node Count Total Actions
1 1
To perform more thorough testing execute code similar to the following. This code will upload a table to the CAS session created earlier and perform basic descriptive statistics on the numeric variable of the dataset. Only a sample of the output is shown here.
casout={name="insighttoy1", replace=true}}
insighttoy1Tbl = {} insighttoy1Tbl.name = result.tableName
insighttoy1Tbl.groupBy = {"Facility"}
stats = {"min", "max", "n", "nmiss", "mean", "std", "stderr"}
results, info = s:simple_summary{table=insighttoy1Tbl, subset=stats}
bgi = results.ByGroupInfo
print(bgi)
Facility Facility_f _key_
0007 0007 0007
0008 0008 0008
0009 0009 0009
000A 000A 000A
000B 000B 000B . . .
for k,v in pairs(results) do
print(k, v)
print()
end
That's all there is to it.
Final Thoughts
In summary the steps include ensuring you have a supported version of Lua and installing one if not available, downloading and extracting the SWAT package if not running on a VDMML machine, and establishing environment variables that provide paths to required components. When these pieces are in place you are ready to begin your adventures in Lua by performing analytics within a CAS session.
References
Getting Started with SAS® Viya™ 3.2 for Lua
Access the download file and instructions: SAS Lua Client Interface for SAS Viya
