PaleoRun is a command line executable that provides users with a means of running one or more PaleoClimate or PaleoGIS jobs in series from the command line. It exposes the most commonly used functions of PaleoGIS and PaleoClimate and provides some additional utility functions as well. With PaleoRun, users can:

Run reconstructions
Run multi-reconstructions
Run animations
Run azimuth and rate vs. time and point path visualization
Run instantaneous motion
Modify metadata
Add layers to a map document and symbolize
Dump the flat rot header
Execute a PaleoClimate run

A single batch script can include one or more of any of the above job types. For example, a user could create a batch script that includes three reconstructions, an animation and a PaleoClimate run. PaleoRun will prove particularly useful when users need to execute a large number of jobs, say dozens of reconstructions when new plate model data is received, or when they need to run one or more long-running jobs. Because it is a command line executable, PaleoRun can be scheduled through the Windows Task Scheduler to kick off reconstructions, animations or climate simulations.

Please note that this application has no GUI; all of its functionality is executed at the DOS command line.

Some of the advantages of using PaleoRun include the ability to:

Script a series of jobs with DOS scripting tools,
Run a series of jobs as a single batch,
Schedule scripted jobs to run at regular intervals,
Schedule long-running jobs overnight or over the weekend,
Re-run job scripts many times.

Installation and Activation

PaleoRun

Download and run the PaleoRun installer.
PaleoRun.exe installs by default in %PROGRAM FILES (x86)%\Rothwell\PaleoRun.
You should have been provided with a PaleoRun license file (.licx) after purchasing. Copy your license file to the PaleoRun installation directory.
Open a command prompt and follow the instructions below in Getting Started with PaleoRun.

Other Dependencies

To execute jobs via PaleoRun, the user must have a license to PaleoRun as well as the other application(s) for which jobs will be run. For example, should the user wish to execute a series of PaleoGIS jobs, then he/she will need an available license to PaleoRun and to PaleoGIS. The license for all products used will be held for the duration of the batch job. This prevents failure partway through the batch due to inability to obtain needed licenses.

Additionally, users must have ArcMap 10.1 or 10.2 installed in order to install and run PaleoRun 1.0.

Getting Started with PaleoRun

PaleoRun can be launched either from the command line or by double clicking on the PaleoRun.exe file. When running from the command line, the XML file can be in any location and have any name, and the path to the XML file must be specified as a command line argument. When running by double clicking on the file, the XML file must be named PaleoRun.xml and it must be in the same directory as PaleoRun.exe.

Syntax

paleorun <path to XML config> Will execute PaleoRun against the XML script specified

paleorun Will execute PaleoRun against PaleoRun.xml located in the same directory as the executable

Options and Arguments

When running a job or set of jobs, PaleoRun takes only one parameter: the name of the XML file that contains the job details. Additionally, PaleoRun has several options, such as --help and --version, which provide information to the user.

Note that the details for how each job is to be run are specified in the XML file, rather than at the command prompt.

Options	Arguments	Description
<path to XML config>		The path to the PaleoRun XML configuration file with the job(s) and job parameters. I.E. C:\Temp\MultiJob.xml.
--help		“Help.” Opens the PaleoRun help documentation in a web browser.
--version		“Version.” Returns the PaleoRun version number.
--proxy		“Proxy Settings.” View or update proxy settings
	--write --ipaddress <ip address> --port <port number> --username <username> --password <password> [--disable --bypassexpect]	Writes proxy settings to a file with the provided parameters. The --disable and --bypassexpect arguments are optional. Example: --proxy --write --ipaddress=127.0.0.1 --port=80 --username=jsmith --password=p@$$w0rd --bypassexpect
	--read	Reads proxy settings from file
	--clear	Clears the proxy settings file
	--disable	Switches the disable setting and writes the new setting to the log file.
	--bypassexpect	Switches the bypass expect 100 setting and writes the new setting to the log file.

Logging

Error, warning and information messages are written to a log file in the PaleoRun installation directory: PaleoRun.log.

Redirecting Output

By default PaleoRun writes all output to the command prompt. The standard DOS output commands can be used with PaleoRun to redirect output as desired.

><path to output file> Writes the command output to a file instead of the command prompt

>><path to output file> Appends the command output to the end of the named file without deleting the information already

present in that file

The above commands are used with Dump Flat Rot Header and Dump Flat Rot routines to save the output to a specific file location, for example: >>output.txt

PaleoRun XML Schema

The PaleoRun XML format can accommodate one to n jobs within one file. Within the <Jobs> parent node, one or more <Job> nodes may be listed. Each Job has a <JobType> such as Reconstruction or Animation and a set of <JobParameters> that provide the details of how that job is to be run. It follows this basic format:

<Jobs>

<Job>

<JobType>Reconstruction</JobType>

●

</JobParameters>

<Job>

Another job

</Job>

<Job>

Another job

</Job>

</Jobs>

</JobXml>

PaleoGIS Jobs in PaleoRun

For PaleoGIS jobs, PaleoRun is flexible and provides batch processing capabilities for a variety of scenarios. Input layers can be shapefiles or personal/file geodatabase feature classes. Outputs can also be any of these 3 types of feature classes. Multiple-age reconstructions can be executed from a single reconstruction job. Finally, multiple jobs of different types can be chained together within one batch XML script.

Reconstruction

Single and multiple age reconstructions are supported.

Below is a sample reconstruction that reconstructs a zinc_lead layer, a Subduction Margin layer and an Oil Source Rock layer to 82.2 Ma using the UTIG demo plate model with no fixed plate. This example demonstrates the use of all three input and output types: file geodatabase, personal geodatabase and shapefile.

<Jobs>

<Job>

<JobType>Reconstruction</JobType>

<CachePath>C:\Users\kbmeinstein\Desktop\BatchTestData\testcache.gdb</CachePath>

<AppSettingsLocation>C:\Program Files (x86)\Rothwell\PaleoGIS\PaleoGIS_settings.mdb</AppSettingsLocation><!--See note* for

more information about the app settings location -->

<LogFileLocation>C:\temp\BatchLog.txt</LogFileLocation>

<Timescale>Berggeren, 2005</Timescale> <!-- (Optional. Only use if you are converting between timescales. IF YOU ARE NOT

CONVERTING BETWEEN TIMESCALES, DELETE THIS ROW -->

<PlateModel>Demo UTIG PLATES Model</PlateModel> <!-- (Use the registered plate model name from PaleoGIS,

not the model .mdb file name -->

<MasterOutput>C:\temp\outputs</MasterOutput> <!-- (Optional, but if not included, each layer must specify an

<Layer>

<Input>C:\temp\DemoData.gdb\zinc_lead</Input>

<Output>C:\temp\zincOutputFile</Output>

</Layer>

<Layer>

<Name>Subduction Margins</Name>

<Input>C:\temp\DataPDB.mdb\Margins</Input>

<Output>C:\temp\margins_output.gdb</Output>

</Layer>

<Layer>

<Name>Oil Source Rock</Name>

<Output>C:\temp\source_rock_output.mdb</Output>

</Layer>

</Layers>

</JobParameters>

<Job>

Another job

</Job>

<Job>

Another job

</Job>

</Jobs>

</JobXml>

*When using PaleoRun with PaleoGIS versions 4.1.x and earlier, use the <appSettingsLocation> path shown in the sample xml above. For version 4.2.x and later the path should be:

C:\Users\username\AppData\Roaming\Rothwell\PaleoGIS\Settings\PaleoGIS_Settings.MDB

where username is your user directory on your computer. This change is necessary because starting in version 4.2 the PaleoGIS settings .mdb is copied to the within your user profile to the location indicated in the above path, and any setting changes you make (such as registering a new model), will be saved in this copy of the settings .mdb, and not in the settings .mdb in the installation directory.

Layers

For each <Layer>:

The <Name> tag is optional. If this tag is left out or is left blank, the output feature class will be given the name of the input feature class.
The <Input> field should contain the path to the input feature class. This feature class can be from a personal or file geodatabase or it can be a shapefile. If this feature class is a shapefile, it must end with the .shp extension. Examples of all three <Input> types are shown in the XML sample above.
The <Output> field is optional. This field specifies the path to the desired output location for the reconstructed feature class. The output location can be a directory or a file or personal geodatabase. If the output location is a directory (as determined by the lack of a .gdb or .mdb extension), the feature class will be saved as a shapefile. Examples of all three <Output> types are shown in the XML sample above. If <Output> is left out or is blank, a <MasterOutput> path must instead be included as a job parameter as described below.

Master Output

An <Output> does not have to be provided for each layer if <MasterOutput> is included as a job parameter. This parameter is the path to an output location that can be a directory or a file or personal geodatabase, just as with an individual <Output>. If a <MasterOutput> path is provided, any <Output> paths will be ignored and reconstruction results for all layers will go to the specified <MasterOutput> location. If layers are being reconstructed to multiple ages, the same sub-directory naming conventions will be used for the <MasterOutput> as would have been used for a regular <Output> path as described in the Multiple Age Reconstructions section below.

Single Age Reconstructions

For reconstructions to a single age, the <ReconstructionAge> field should contain a single number. For single age reconstructions, a single output for each layer will be written to the specified output location.

Multiple Age Reconstructions

For reconstructions to multiple ages, the <ReconstructionAge> field should contain either a comma separated list of the reconstruction ages (e.g., 40.5, 63.7, 96, 103.2) or for reconstructions at regular intervals the ages should be entered as Start Age (inclusive), End Age: Step Interval (e.g., 0,50:10). Reconstructions to Age = 0 will be skipped, so for 0,50:10, reconstructions will be performed for 10, 20, 30, 40 and 50 Ma. All of the layers in the job will be reconstructed to each age.

If the output location for a layer is a directory, a new directory will be created for each reconstruction age with the age appended to the directory name. For example:

Output = C:\temp\zincOutput

Reconstruction ages = 40.5, 63.7, 96, 103.2

The following directories will be created to contain the output shapefile from each reconstruction:

C:\temp\zincOutput\40.5\

C:\temp\zincOutput\63.7\

C:\temp\zincOutput\96\

C:\temp\zincOutput\103.2

If the output location for a layer is a geodatabase (personal or file), a new geodatabase will be created for the output from each reconstruction age with the age appended to the geodatabase name. For example:

Output = C:\temp\source_rock_output.mdb

Reconstruction ages = 40.5,63.7,96,103.2

The following directories will be created to contain the output shapefile from each reconstruction:

C:\temp\40.5\source_rock_output.mdb

C:\temp\63.7\source_rock_output.mdb

C:\temp\96\source_rock_output.mdb

C:\temp\103.2\source_rock_output.mdb

Reconstruction Output Geodatabase

The outputs from all batch reconstructions are initially written to a file geodatabase before being copied to their final output locations/formats. This reconstruction geodatabase is located in the same directory as the cache. The name is name of this geodatabase is scratch.gdb, since this is just an intermediate output location.

Animation

The following script demonstrates an animation job that reconstructs the UTIG_demo plate model from the present day to 10 Ma in 5 steps with a specific view extent.

<Jobs>

<Job>

<JobType>Animation</JobType>

<CachePath>C:\Workspace\PaleoGIS\Jobs\17\temp\cache.gdb</CachePath>

<AppSettingsLocation>C:\Workspace\PaleoGIS\Settings\PaleoGIS_Settings.mdb</AppSettingsLocation>

<LogFileLocation>C:\Workspace\PaleoGIS\Logs\PaleoGIS.JobService.17.log</LogFileLocation>

<Layer>

<Input>C:\Workspace\PaleoGIS\PlateModels\UTPlates\Shapefiles\UTIG_demo.shp</Input>

<Output>C:\Workspace\PaleoGIS\Jobs\17\Outputs\PlateModels\1</Output>

</Layer>

</Layers>

</Extent>

</JobParameters>

</Job>

</Jobs>

</JobXml>

Azimuth and Rate vs. Time and Point Path Visualization

The Azimuth & Rate vs. Time analysis graphically shows the speed and direction of movement for a single point on a single plate over a specified time range at specified step intervals. The position, azimuth and speed of the point is calculated for each step interval from present to past. Point Path Visualization adds a line to the map showing the path of the point over the specified time period, and the width of the path indicates the speed of the point at different times.

This sample Azimuth and Rate vs. Time and Point Path Visualization job demonstrates the speed and direction of movement of a point located at 23.88671, 78.432120 from the present day to 40 Ma in 5 Ma steps. The Azimuth and Rate vs. Time output will be saved as two bitmaps (.bmp) to C:\Workspace\PaleoGIS\Jobs\999\Outputs\Azimuth.bmp and C:\Workspace\PaleoGIS\Jobs\999\Outputs\Rate.bmp. The point path output will be saved as a shapefile and layer file, PointPathVisualization.shp and PointPathVisualization.lyr respectively.

<Jobs>

<Job>

<JobType>AzimuthRatePathVsTime</JobType>

<CachePath>C:\Workspace\PaleoGIS\Jobs\999\temp\cache.gdb</CachePath>

<AppSettingsLocation>C:\Workspace\PaleoGIS\Settings\PaleoGIS_Settings.mdb</AppSettingsLocation>

<LogFileLocation>C:\Workspace\PaleoGIS\Logs\PaleoGISPaleoGIS.JobService.999.log</LogFileLocation>

<HalfRateMethod>False</HalfRateMethod>

<AzimuthGraphImage>C:\Workspace\PaleoGIS\Jobs\999\Outputs\Azimuth.bmp</AzimuthGraphImage>

<RateGraphImage>C:\Workspace\PaleoGIS\Jobs\999\Outputs\Rate.bmp</RateGraphImage>

<PathShapefile>C:\Workspace\PaleoGIS\Jobs\999\Outputs\PointPathVisualization.shp</PathShapefile>

<PathLayerfile>C:\Workspace\PaleoGIS\Symbology\PointPathVisualization.lyr</PathLayerfile>

</JobParameters>

</Job>

</Jobs>

</JobXml>

Instantaneous Motion

The Instantaneous Motion tool draws a regularly-spaced grid of arrows on a reconstructed map to show the speed and direction of motion for the location under each arrow at that time.

The following script creates an Instantaneous Motion job using the UTIG_demo plate model with no fixed plate and a grid increment of 4 degrees over the entire globe. To specify an extent, use <UseAoi>true</UseAoi> and coordinates in the <Extent>.

<Jobs>

<Job>

<JobType>InstantMotion</JobType>

<CachePath>C:\Workspace\PaleoGIS\Jobs\998\temp\cache.gdb</CachePath>

<AppSettingsLocation>C:\Workspace\PaleoGIS\Settings\PaleoGIS_Settings.mdb</AppSettingsLocation>p

<LogFileLocation>C:\Workspace\PaleoGIS\Logs\PaleoGIS.JobService.998.log</LogFileLocation>

<UseAoi>false</UseAoi>

</Extent>

<InstantMotionShapefile>C:\Workspace\PaleoGIS\Jobs\998\Outputs\InstantaneousMotion.shp</InstantMotionShapefile>

<InstantMotionLayerfile>C:\Workspace\PaleoGIS\Symbology\InstantaneousMotion.lyr</InstantMotionLayerfile>

</JobParameters>

</Job>

</Jobs>

</JobXml>

Modify Metadata

The Modify Metadata job type replaces or appends the value of a metatdata element. The Modify Metadata job type works for feature classes and layer files. It also works for rasters if stored in file or personal geodatabase.

To replace the existing value use <ActionUpdateOrReplace>REPLACE</ActionUpdateOrReplace>.

To appended to the existing value use <ActionUpdateOrReplace>UPDATE</ActionUpdateOrReplace>.

This sample Modify Metadata job will replace the value of a metadata element named idinfo/descript/purpose in the PLATES000 feature of the Lausanne_2011 personal geodatabase.

<Jobs>

<Job>

<JobType>ModifyMetadata</JobType>

<FileLocation>c:\work\Lausanne_2011.mdb</FileLocation>

<NameofFiletoModifyMetadata>PLATES000</NameofFiletoModifyMetadata>

<ElementNameToUpdate>idinfo/descript/purpose</ElementNameToUpdate>

<NewValue>NO_CACHE;NO_DELETE_AFTER_RECONSTRUCTION;TIMESLICE_APPEARANCE=000;TIMESLICE_DISAPPEARANCE=-001;</NewValue>

<ActionUpdateOrReplace>REPLACE</ActionUpdateOrReplace>

</JobParameters>

</Job>

</Jobs>

</JobXml>

Add Layer to MXD and Symbolize

This job adds layers to a map document in ArcMap. It treats multiple layers and single layers similarly. For each layer to be added to the MXD, an <MXDLayer> group must be added to the XML in the <MXDLayers> section. (See example below.) Each <MXDLayer> group must contain all of the XML fields even if they are not needed. Unused fields should be left empty. The <PathToMXD>, <DataToAddAsFullPath>, and <DataFrameToAddLayerTo> fields must always contain valid data. If <NameOfLayerInTOC> is left blank, the layer will be automatically named “New Data Layer” in the Table of Contents. If multiple unnamed layers are added, they will be named “New Data Layer” , “New Data Layer2”, “New Data Layer3” , etc.

This sample adds a WellData.shp shapefile to the North America\Data\Wells group layer of the Well Map data frame of WellMap.mxd as My Wells Data Layer, using symbolization from the wellDataSym.lyr layer file.

<Jobs>

<Job>

<JobType>AddLayerToMXDAndSymbolize</JobType>

<PathToMXD>%temp%\WellMap.mxd</PathToMXD>

<DataToAddAsFullPath>C:\Temp\WellData.shp</DataToAddAsFullPath>

<NameOfLayerInTOC>My Wells Data Layer</NameOfLayerInTOC>

<PathToLayerFile>C:\Trglp\Development\PaleoGIS\data\wellDataSym.lyr</PathToLayerFile>

<GroupLayerPath>North America\Data\Wells</GroupLayerPath>

</MXDLayer>

Another layer

</MXDLayer>

Another layer

</MXDLayer>

</MXDLayers>

</JobParameters>

</Job>

</Jobs>

</JobXml>

Working with Flat Rot Tables

PaleoGIS optionally supports the use of a “Flat Rot” table with a plate model. A Flat Rot table stores pre-calculated total finite poles for one or more ages that can be used to rotate the geometries, instead of calculating these poles at runtime.

In PaleoRun, the Dump Flat Rot Header job is used to create the schema for Flat Rot tables, and the Dump Flat Rot job is used to populate the schema with the calculated values for the total finite poles.

These two job types are always run together.

The output of these jobs can either be written to an Access database (.mdb) or to a text file. Be sure to use the standard DOS syntax for writing to an output file (the > and/or >> commands).

1) To dump to an Access database, specify the path to the Access database (.mdb), and the name of the table in the XML file.

2) To dump to a text file, run the application from the command line or a .bat file with the text file output path as follows:

To capture it to a new file use:

PaleoRun.exe C:\Path\config.xml >dump_file.txt

To append it to an existing file use:

PaleoRun.exe C:\Path\config.xml >>dump_file.txt

If this routine is run without the > or >> commands, PaleoRun will dump the output to the console.

3) PaleoRun will dump the output to the console if the > and/or >> commands are not used.

Question

Dump Flat Rot Header

In this sample DumpFlatRotHeader job, a new table called MyTable is being created within the database MyGeodatabase.mdb to store pole rotation data. When writing the output to an Access database table, two arguments are required: the path to the Access database (.mdb), and the name of the table. It will then create the table in the Access database with the required fields.

<Jobs>

<Job>

<JobType>DumpFlatRotHeader</JobType>

<PathToOutputMDB>C:\Temp\MyGeodatabase.mdb</PathToOutputMDB>

<TableName>MyTable</TableName>

</JobParameters>

</Job>

</Jobs>

</JobXml>

When writing output to a text file, the <JobParameters> tag should be empty (<PathToOutputMDB> and <TableName> must be empty or non-existent), and PaleoRun must be launched as a console application using the > and/or >> commands as described above. PaleoRun will dump the output to the console if the > and/or >> commands are not used.

<Jobs>

<Job>

<JobType>DumpFlatRotHeader</JobType>

</Job>

</Jobs>

</JobXml>

Dump Flat Rot

This function outputs all the total finite absolute poles for a particular plate model in a particular reference frame for ages at specified increments over a specified age interval. The DumpFlatRotHeader routine should be called before this function. Pole rotation data cannot be written if the table does not exist.

This

<Jobs>

<Job>

<JobType>DumpFlatRot</JobType>

<PlateModel>TestModel </PlateModel>

<PlateModelPath>C:\Temp\TestModel.mdb</PlateModelPath>

<PlateModelSettingsTable>T_Model_Settings </PlateModelSettingsTable>

</JobParameters>

</Job>

</Jobs>

</JobXml>

2) Dump to Access database table:

This will always append to what is already in the table, so make sure the table is absent or empty if a new dataset is required.

<Jobs>

<Job>

<JobType>DumpFlatRot</JobType>

<PlateModel>TestModel </PlateModel>

<PlateModelPath>C:\Temp\TestModel.mdb</PlateModelPath>

<PlateModelSettingsTable>T_Model_Settings </PlateModelSettingsTable>

<OutputTable>C:\Trglp\Development\PaleoGIS\Data\GlobalV3.mdb\flat_rot</OutputTable>

</JobParameters>

</Job>

</Jobs>

</JobXml>

PaleoClimate Jobs in PaleoRun

PaleoRun can execute one or more PaleoClimate modeling runs using the “Climate” parameter for <JobType> as shown below. One or more PaleoClimate jobs can be run in the same batch with PaleoGIS jobs, or alone. PaleoClimate uses an XML config file called Config.xml to specify the numerous input parameters it takes, even when being run independently of PaleoRun. Everything within the <JobParameters> tag of PaleoClimate’s Config.xml can be pasted directly into the <JobParameters> tag of a PaleoRun batch script.

<Jobs>

<Job>

<JobType>Climate</JobType>

PaleoClimate job parameters

</JobParameters>

</Job>

</Jobs>

</JobXml>

The full PaleoClimate XML schema specification can be found in the PaleoClimate User’s Manual.

Product Support

The Rothwell Group, L. P. provides PaleoRun product support for all users. For any questions concerning PaleoRun, please contact us:

www.paleogis.com/support

support@rothwellgroup.com

The Rothwell Group, L.P. www.paleogis.com