Cerius2 Modeling Environment

13       Scripts and Licensing

All Cerius² applications, including the Visualizer, are command driven. The graphical interface takes your input (mouse clicks and drags, etc.), continuously translates it into commands, records the commands into logs, and passes the commands to the programs themselves.

Although many users generally need to know nothing about this process, you may want to learn about creating and using Cerius² commands, to facilitate performing a series of related or identical tasks in an automated way.

You may also want to know about Cerius²'s facilities for running application modules on remote machines and for managing licenses.

This section explains

This section contains information on:

Command logging and scripting

Controlling Cerius2 from scripts

Managing licenses

Running application modules externally

You should already know...

The basics of starting Cerius² and using its interface are demonstrated in Introducing Cerius2 and described in The Cerius2 Interface.

Command logging and scripting

Finding information

This section includes information on:

Recording commands

Command tracing

Command scripts can be played back later (Playing back scripts and log files) unmodified, to repeat a previous session. Alternatively, you can supplement a command script with Tool Command Language (Tcl) statements to produce responsive, program-like scripts that can be used to drive Cerius² and its applications.

Related information

To learn more about using Tcl to enhance script files, see Cerius² Command Script Guide, as well as information in the documentation and support areas of our website

http://www.msi.com/doc/

http://www.msi.com/support/

During every Cerius² session, generated commands are continuously logged to a file named RUN.LOG. This continuous log file provides a record of the modeling activity that took place in a Cerius² session.

The RUN.LOG file is normally overwritten when a new Cerius² session is started; however, the contents of the current RUN.LOG file (that is, the session log) can be saved under another filename at any time. Such files provide a snapshot of the session at a particular time.

You can also open a supplementary log file, called a segment log file, into which all generated commands are logged until this file is closed. A segment log file enables you to create a log of only part of a session (for example, only that part of a session from which you want to create a command script). Command logging to RUN.LOG also continues, regardless of whether a segment log file is open.

Accessing the tools

Select the Utilities/Record Commands... menu item in the main Visualizer control panel to access the Record Commands control panel.

Recording commands

To copy all the current contents of the RUN.LOG file to a file with a different name, change the filename in the entry box near the top of the Record Commands control panel (if desired) and click the Dump current Log contents action button.

To start copying commands into a supplementary log file, check the Echo commands into file check box. All subsequent commands appear in both the RUN.LOG file and the segment log file.

To discontinue copying commands into the supplementary log file, uncheck the Echo commands into file check box. If you want to record more commands into the same file later in your session, simply check the Echo commands into file check box again.

To enter a comment in the current RUN.LOG file (and the current segment log file, if one is open), enter the desired text into the Enter Comment into Log File entry box.

Managing command logs

To empty and restart the current RUN.LOG file from the current point in your Cerius² session, click the Empty Log File contents action button in the Record Commands control panel. This action does not reinitialize the Cerius² session (Starting a new session), it merely restarts the log file.

Additional information

Please see the on-screen help for details on the functioning of each control in the Record Commands control panel.

Command tracing

Levels of commands

Three levels of commands are generated by the graphical interface and application modules:

• Primary--Generated by primary command generators, such as the graphical interface or a script file, or by your direct entry of commands in the text window.

• Secondary--Generated directly or indirectly by application modules as a result of processing a primary command.

• Utility--Generated internally within Cerius², for defining the environment in which Cerius² and its application modules are to run (for example, the commands generated when command tracing is turned on or off).

Select the Utilities/Command Tracing... menu item in the main Visualizer control panel to access the Command Tracing control panel.

What level of commands to trace

To specify the level (see Levels of commands) of commands to trace, check one or more of the Activate Command Tracing check boxes.

Tip

Where to send the commands

To display the traced commands in the text window, check the Text Window check box.

To log the traced commands in a file, check the Trace File check box and (if desired) enter a filename in the Trace File entry box.

Changing command tracing

To stop command tracing or change the level of commands to trace, uncheck the relevant check boxes in the Command Tracing control panel.

Examining most recent commands

To print the most recent primary and utility commands in the text window, enter the command history in the text window.

Additional information

Please see the on-screen help for details on the functioning of each control in the Command Tracing control panel.

Some additional control over command logging and history is accessible via the Customize Environment control panel (Accessing the tools).

Controlling Cerius2 from scripts

Command logging and scripting utilities enable you to record Cerius² commands (Recording commands) into script files and play them back at a later time.

Command scripts are often based on Cerius² log files, which can be used unmodified, to repeat a previous session. Alternatively, you can supplement a log file with Tool Command Language (Tcl) statements to produce responsive, program-like command scripts that can be used to drive Cerius² and its applications. In addition, you can write command scripts completely from scratch.

Finding information

This section includes information on:

Playing back scripts and log files

Starting Cerius2 with a command script file

Related information

To learn more about using Tcl to enhance script files, see Cerius² Command Script Guide.

You should already know...

Recording commands is discussed under Command logging and scripting.

Playing back scripts and log files

Accessing the tools

Select the Utilities/Playback Script... menu item in the main Visualizer control panel to access the Playback Script control panel.

Finding the script file

Use the file browser and selector tools to find and choose the desired script file. How to use these tools is detailed under Finding model file(s). (All file browsers work similarly.)

Playing back Cerius² scripts

You can play back the script file in several ways:

• To simply run the script now, click the RUN pushbutton in the Playback Script control panel.

• To reinitialize the session (Starting a new session) before running the script, check the Re-initialize check box and then click the RUN pushbutton.

• To run the script repeatedly (reinitializing the session before each pass through the script), check the Run Script Repeatedly check box and then click the RUN pushbutton.

Please see the on-screen help for details on the functioning of each control in the Playback Script control panel.

Starting Cerius2 with a command script file

Cerius² can also be run from a recorded script, either with or without the graphical interface. You can manually specify the script when you start Cerius² or have Cerius² always process a certain script automatically without your needing to specify it.

Ways of automating Cerius²

You can run Cerius² from a command script in several ways:

• With the graphical interface--automatically process the commands immediately when Cerius² starts, then await your additional input (see Starting Cerius2 with an automatic script and Starting Cerius2 with a specified script).

• With the graphical interface--process the commands when you request it, then await your additional input (see Playing back scripts and log files).

• Without the graphical interface--as a foreground job, process the commands automatically, then exit (see Running Cerius2 without the graphical interface).

• Without the graphical interface--as a background job, process the commands automatically, then exit (see Running Cerius2 without the graphical interface).

If you have certain tasks that you always or often perform when you start a Cerius² session, you can record them in a command script file, and then have Cerius² automatically perform these tasks from the script, either immediately (this section) or when you request it (Playing back scripts and log files). Then you can proceed with additional tasks using the graphical interface.

If you have repetitive, routine calculations or other tasks that can be performed without the graphical interface, you can record these tasks in a command script file. Then you can run Cerius² in a completely automated way, in either the foreground or background, without your interacting with the graphical interface at all.

Starting Cerius² with an automatic script

To run Cerius² from a command script with the graphical interface and have it immediately and automatically process a certain command script, move (cd) to a directory containing an initialization script, then simply start Cerius² as usual.

An initialization script is simply an ordinary command script file that you have saved with the filename cerius2.ini (see Recording commands).

To set up different initialization scripts for use when you run Cerius² for different purposes or projects, simply create separate directories, each containing a different cerius2.ini file. If Cerius² does not find a cerius2.ini file in the directory in which you start it, it looks for a cerius2.ini file in your home directory.

After the initialization file's command script terminates, Cerius² enters interactive mode, awaiting your input.

Starting Cerius² with a specified script

To run Cerius² from a command script with the graphical interface and have it immediately process a specified command script, start Cerius² by entering at the system prompt:

>	cerius2 scriptfile 

To run Cerius² from a command script with the graphical interface, have it immediately process a specified command script, and have it send any text output to a file instead of to the text window, start Cerius² by entering at the system prompt:

>	cerius2 -o outputfile scriptfile 

In either case, graphics are displayed in normal fashion in the model window. After the command script terminates, Cerius² enters interactive mode, awaiting your input.

Running Cerius² without the graphical interface

To run Cerius² without the graphical interface in background mode, enter at the system prompt:

>	cerius2 -b outputfile scriptfile 

To run Cerius² without the graphical interface in foreground mode, enter at the system prompt:

>	cerius2 -n -o outputfile scriptfile 

To run Cerius² without the graphical interface in foreground mode and send any text output to the shell window rather than to a file, enter at the system prompt:

>	cerius2 -n scriptfile 

Managing licenses

When to manage licenses

Some situations exist in which you may want to manage licenses interactively, for example:

• Suppose your site has a limited number of licenses and they are all being used by other people. If you need a license, you may want to determine who the other users are. Then you can ask one of them to replace (that is, check in) the license so that you can work.

• If you plan to run a long command script, you may want to reserve (that is, check out) enough licenses to assure that they are available when needed.

Important

Accessing the tools

Select the Utilities/Application Licensing... menu item in the main Visualizer control panel to access the License Management control panel.

For all of the functions below, select the name of the desired module in the Available Licenses list box. This list box shows the names of modules that require licenses and for which you have purchased licenses.

What licenses are available?

The Available Licenses list box shows the names of modules that require licenses and for which you have purchased licenses.

The total number of supported floating licenses (i.e., module-specific licenses that your site has purchased) for a selected module appears near the bottom of the License Management control panel.

The total number of people currently using floating licenses for that module is listed in the line below the total number supported.

Who are using other licenses?

The login name(s) of the people using floating licenses for the selected module are shown in the Checked out to list box.

For token licenses, this user list appears only if you currently have the selected feature checked out via token licensing. This list of users includes the total number of tokens each person has checked out (in parentheses after their name). However, it does not indicate which people have a particular feature checked out. When you check out a feature, the indicated total number of tokens by your name is increased.

Reserving licenses

To manually reserve (check out) one floating licence for the selected module, click the name of the selected module in the Available Licenses list box or click the CHECK OUT pushbutton.

To manually reserve several token licenses for a specific feature, user, or machine, please see the Cerius2 Installation and Administration Guide on using an options file.

Releasing licenses

To return (check in) a license that you have checked out manually for a selected module but are finished using, click the name of the selected module in the Available Licenses list box or click the CHECK IN pushbutton.

Additional information

Please see the on-screen help for details on the functioning of each control in the License Management control panel.

For additional information about a particular license (i.e., when it expires and what machine is serving it), click the License pushbutton.

For more information about licensing (including the differences between token and floating licenses and between features and modules) and license management, please refer to the Cerius2 Installation and Administration Guide.

Running application modules externally

Cerius² applications are implemented as modules that plug into the modeling environment provided by the Visualizer. Most Cerius² application modules function (either individually or grouped with related modules) as independent processes. As a result, these application modules can be run on your local machine or externally on a remote host (of the same or different type) anywhere on your network.

Uses of remote servers

This implementation method has several advantages, including:

• You can start and run only the application module(s) that you want to use, thereby saving memory and reducing overhead.

• You can purchase licenses to run application modules only on certain machines and still control those modules from any other machine on your network.

• You can run application modules that perform complex, computationally intensive calculations on remote servers, which may be more powerful than your own (local) machine.

To run application modules externally, you use the controls on the Process Management control panel to select the appropriate application module, process, remote host, and executable program, to modify any of your selections (if necessary), and to specify that the module should be started either immediately or when the module is accessed from a menu card. Once you have started an application module on a remote host, you can also use the Process Management control panel to stop that module's process.

Tip

Cerius² and independent processes

Some application modules (for example, those on the QUANTUM cards) are actually used only to set up and act as interfaces to calculations that are run by essentially separate programs that are independent of the Cerius² interface. Such modules offer their own job-control options that affect the separate (usually computationally intensive) program. These controls are accessed from the application module itself and are documented in the user guide for the relevant module.

The Process Management control panel affects only those processes that are under the direct control of the Cerius² interface, not independent processes that are spawned by applications such as the quantum modules.

For example, the MOPAC interface application (control panels, etc.) is controlled by the Process Management control panel, but the MOPAC program itself (the calculation job) is managed by MOPAC Job Control control panel.

Accessing the tools

Select the Utilities/External Processes... menu item in the main Visualizer control panel to access the Process Management control panel.

Specifying processing conditions

To specify what process you want to start or stop, select its name from the Application list box in the Process Management control panel. The name of the relevant process appears in the Process list box.

Tip

The names of machines on your network appear in the Host list box. Select the one that you want to send the process to. (The machine you are running Cerius² on is called localhost.) If a machine's name is not on that list but you know it is accessible from your machine, you can enter its name in the Remote Host entry box.

If you need a password in order to use the specified machine, enter it in the Password entry box.

Tip

To specify your working directory on the specified host, if it does not appear automatically, enter the name of your working directory in the Working Directory entry box. This directory must already exist.

If more than one executable can run on the chosen machine, select the name of the desired executable in the Executable list box. You can also enter the complete path and file name of the executable in the Executable entry box.

(The registry information contained the list boxes in this control panel can become outdated if changes are made after Cerius² was installed at your site. To update this information, your installation administrator needs to edit the applcomm.db file. For additional information on this file, please see the Cerius2 Installation and Administration Guide.)

Starting an external process

You can start the specified Cerius² process on an external host in two ways:

• To save the settings for use later in the current session, so that the process is started as instructed only when you access the application module from its menu card, click the Save Selection action button.

• To start the process immediately, click the Start action button. The process starts, but does not do anything other than wait for your additional input from the application module's menu card.

To stop running the selected Cerius² process on the specified host, click the Kill action button. You would typically use this button if you want to restart the selected process on another host.

Additional information

Please see the on-screen help for details on the functioning of each control in the Process Management control panel.

Related information

Executing Cerius² on one machine while displaying its interface on another is discussed in the Cerius2 Installation and Administration Guide.