QUICK GUIDE
1. Read a geometry file and establish the initial condition for the fluid transfer sequence.
2. Start the XFER Wizard from the pull down menu or type "run XFER.WIZCO".
3. Enter the fluid transfer sequence or read an input file.
4. Construct an Evaluation macro.
5. Specify the evaluation triggers.
6. Start a report and press Go.

OVERVIEW

The Liquid Transfer Wizard allows the user to describe and analyze a series of liquid loading changes.  The main wizard dialog provides a form to enter the details of the transfer steps, each of which describes a single operation in a set of liquid transfers.  

USER INPUT
Each step must specify either a source or receiving tank.  For internal transfers, both receiving and source tanks are specified.  In addition, each step must specify a start time, stop time, weight of fluid to be transferred, and rate of transfer.  Times are entered in hours & minutes, however the wizard converts all times and performs internal calculations in minutes.  Rates are specified in the current weight units per minute. 

The form presents four tools to assist in specifying the inputs for each plan step:
1) The "Empty" button calculates the weight of fluid currently in the "From" tank and populates the Weight field for the given step with that value.
2) The "Fill" button calculates the weight of fluid required to completely fill (loaded to 100%, respecting the tank's permeability) the "To" tank and populates the Weight field with that value.
3) The "Update" button takes an arbitrary three inputs of Start, Stop, Weight, and Rate fields and calculates the fourth value.  For example, If a start, stop and weight are specified, the "Update" button will provide the associated rate.
4) A volume converter tool (accessed from a button on the Liquid Transfer Wizard) assists the user in converting from various volumes to the weight of fluid to be transferred in a given plan step.
5) A delete "x" button which deletes a particular plan step.

Input Validation
1) The wizard does not support mixing fluids of different specific gravities. When multiple tanks are specified, the form verifies that the specified tanks contain fluids with the same specific gravity.
2) The use of the "Empty" and "Fill" buttons when two tanks are specified triggers a check that the source tank can provide sufficient fluid in the case of a "Fill".  Similarly, the receiving tank is checked for sufficient capacity in the case of an "Empty".  If the transfer is limited by source or receiving capacity, the weight of fluid specified for the step is truncated to reflect the limitations of the associated tank volumes.
3) It is possible to specify an inconsistent set of inputs in the Start, Stop, Weight, and Rate fields for each plan step.  To prevent this, the form provides a warning when the step is either incomplete or has inconsistent inputs.


TIMELIME GENERATION
After clicking the "Save & Go" button, the wizard determines minimum start time and maximum stop time across all specified steps.  Starting at the minimum start time, for each time step, the wizard loops through all plan steps.  If the current time step is between the start and stop times for a given step then an amount of fluid is transferred in accordance with the the definition of the plan step.  Steps are evaluated in the order they are defined.  If a step cannot be completed because there is not enough fluid in a tank or the receiving tank does not have sufficient empty volume, the wizard will transfer as physically possible.  In addition, if the "Log Errors" box is checked the wizard will note any in text file called TRANSFER_ERRORS.txt and warn the user at the completion of the timeline.  

ANALYSIS 
The wizard executes the Evaluate Macro at user specified intervals (e.g. every 30 minutes).  The user can specify the evaluate macro to be executed at the start and or conclusion of each plan step.  In each case, all liquid transfer steps for time "t" are executed prior to execution of the Evaluate Macro and any associtated report output is generated. In addition, a save file can be generated at interval in order to return to the intermediate load case. 
Note: If the user creates an Evaluate Macro which alters the contents or loads of tanks involved in the transfer plan, the wizard will continue to execute the plan as initially specified.


INPUT & OUTPUT FILES
The wizard can read and write the details of the liquid transfer steps to a comma separated value (csv) file located in the working directory.  This file must be called TRANSFER.PLAN.
The schema for the for TRANSFER.PLAN is as follows (empty fields are permitted throughout):
Source Tank, Destination Tank, Start Time (minutes), End Time (minutes), Weight to be transferred, Rate of Transfer (weight/minunte)

The "Write Input File" button also stores the details of the desired analysis in a file called OUTPUT.PLAN
This file has the following structure:
   Set OutInt = [time] 
   `Time in minutes between Evaluate Macro executions
   Set OutStart = 1 or 0 
   `Flag for running Evaluate Macro at the start of each plan step.
   Set OutStop = 1 or 0 
   `Flag for running Evaluate  Macro at the end of each plan step.
   Set OutSave = 1 or 0 
   `Flag for making a save file at each execution of the Evaluate Macro.
   Report [filespec]

The user specified Evaluate Macro is stored in a file called EVALUATE.PLAN which has the following structure:
   Macro Evaluate
	Page 97%
	%1
	`User provided analysis for each analysis step goes here:
	
   /
   
   
MACROS (From xfer.lib)

TRANSFER Weight [FromTank] [ToTank]
This macro transfers a liquid load from one tank to another. 
Parameters: 
Weight parameter is required and specifies the quantity of fluid to be transferred.
FromTank specifies the source of the fluid.  If the source of the transfer is off the vessel (on loading) then "None" should be used for the FromTank parameter.
ToTank specifies the receiving tank.  If the destination of the transfer is off the vessel (lightering/offloading) then "None" should be used for the ToTank parameter.
Operation:
The Transfer Macro works by adding the "Weight" of fluid to current load in the "ToTank" (if specified) and removing that same quantity of fluid from the current load of the "FromTank".  In the case where the FromTank does not contain sufficient fluid, or the "ToTank" doesn't have sufficient capacity to complete the transfer as specified, the weight of fluid transferred is truncated accordingly.

TIMELINE
This macro initiates the time line and calls the TimeStep macro to perform the individual time steps in the plan.  It calls the Min and Max macros to determine the smallest start time and largest stop time across all steps in the plan. 

TIMESTEP Time
This macro is executed once per time step.  It records the current time in the output file and calls the StepLoop macro to execute each step in the plan.  It calls the Evaluation macro to perform an arbitrary analysis at the conclusion of each time step.  It also generates output to a report file based on the user specified output options.

StepLoop Time
This macro is executed once per plan step for each time step when called by the TimeStep macro.  For each plan step, if the current time passed by the "Time" parameter is between the start and stop times, then the Transfer macro is called to perform the transfer specified by the plan.
