pysawit module

PySawit: Oil palm growth and yield model.

This program can run in three modes:

    1. Run model simulations (daily and hourly run)
    2. Output weather/meteorology statistics
    3. Create visualization network graph files

OPTION (1a) - DAILY MODEL RUN

Usage (for daily model simulations):

    pysawit.py run -i <input file>
                   -o <output file>
                   -n <duration>
                   -e <Excel workbook name> (optional)
                   -m <macro name and arguments> (optional)

where flags:

    run is to specify either a daily or hourly model run
    -i is the path and filename to the model input (initialization) file
    -o is the path and filename of the model output (results) file
    -n is the number of simulation days
    -e (optional) is the full path name of an Excel workbook
    -m (optional) is the name of the VBA macro in the Excel workbook to run.
       If the flag -e is specified, this flag -m must be specified too.
       If the macro contains one or more arguments, they must be specified after
       the macro name, where each argument is separated by a space.

Example

On the commandline, you will type the following in only one line

    pysawit.py run -i "C:\Users\adminuser\input.txt"
                   -o "C:\Users\adminuser\output.txt"
                   -n 3650
                   -e "C:\Users\adminuser\export.xlsm"
                   -m ImportResults A1 3650

where

    1) "input.txt" is the model input file and "output.txt" is the model output
       file. Both of these files are in the "C:\Users\adminuser\" folder.
    2) The model will run for 10 years (n = 10 x 365 = 3650 days).
    3) Upon model completion, the model results will be exported to "export.xlsm"
       Excel workbook.
    4) "ImportResults" is the name of the macro in "export.xlsm" that will
       triggered to run, such as to import the model results, and "A1" and "3650"
       will be passed into the macro as its arguments.

Note

If the flag -e is not specified, no export to Excel will be carried out, even if the flag -m is specified.

Important

Excel export function works only in the Windows operating system.

Note

File paths must be enclosed with double quotes, particularly if the file paths contain spaces.

OPTION (1b) - HOURLY MODEL RUN

Usage (for hourly model simulations):

    pysawit.py run -i <input file>
                   -o <output file>
                   -e <Excel workbook name> (optional)
                   -m <macro name and arguments> (optional)

where flags

    run is to specify daily or hourly model run
    -i is the path and filename to the model input (initialization) file
    -o is the path and filename of the model output (results) file
    -e (optional) is the full path name of an Excel workbook
    -m (optional) is the name of the VBA macro in the Excel workbook to run.
       If the flag -e is specified, this flag -m must be specified too.
       If the macro contains one or more arguments, they must be specified after
       the macro name, where each argument is separated by a space.

Note

Running the hourly model simulation is exactly the same as running for the daily model simulations, except without the duration flag -n. If the -n flag is specified, daily model run will be assumed. Removing the -n flag runs the hourly model simulations.

Note

Hourly model simuations is always at one hour time increment from hour 0 to 24.

Note

File paths must be enclosed with double quotes, particularly if the file paths contain spaces.

OPTION (2) - WEATHER STATISTICS

Usage (for weather/meteorology statistics):

    pysawit.py met -i <input file>
                   -o <weather file>
                   -a
                   -e <Excel workbook name> (optional)
                   -m <macro name and arguments> (optional)

where flags

    met is to specify weather/meteorology statistics
    -i is the path and filename to the model input (initialization) file
    -o is the path and filename of the weather file
    -a (optional) means to append the weather stats to the existing weather
       file. If the weather file does not exist, a new one will be created.
       Omit the -a flag to create a new file or to overwrite the existing file.
    -e (optional) is the full path name of an Excel workbook
    -m (optional) is the name of the VBA macro in the Excel workbook to run.
       If the flag -e is specified, this flag -m must be specified too.
       If the macro contains one or more arguments, they must be specified
       after the macro name, where each argument is separated by a space.

Example

On the commandline, you will type the following in only one line

    pysawit.py met -i "C:\Users\adminuser\input.txt"
                   -w "C:\Users\adminuser\wthr-stats.txt"

where

    1) "input.txt" is the model input file
    2) "wthr-stats.txt" is the weather file. This is the file in which the
       weather statistics will be written.
    3) Since the -a flag is not specified, the weather file will be created.
       If the 'wthr-stats.txt' file already exists, it will be overwritten
       without notice.

Note

Both of the input and weather files are in the "C:\Users\adminuser\" folder.

Note

File paths must be enclosed with double quotes, particularly if the file paths contain spaces.

OPTION (3) - NETWORK GRAPH

Usage (for creating visualization graph files):

    pysawit.py net -i <input file>
                   -o <visualization graph file>
                   -e <Excel workbook name> (optional)
                   -m <macro name and arguments> (optional)

where flags

    net is to specify the creation of network graphs to depict program flow
    -i is the path and filename to the model input (initialization) file
    -o is the path and filename of the visualization graph files (DO NOT specify
       the file extension)
    -e (optional) is the full path name of an Excel workbook
    -m (optional) is the name of the VBA macro in the Excel workbook to run.
       If the flag -e is specified, this flag -m must be specified too.
       If the macro contains one or more arguments, they must be specified after
       the macro name, where each argument is separated by a space.

Example

On the commandline, you will type the following in only one line

    pysawit.py net -i "C:\Users\adminuser\input.txt"
                   -o "C:\Users\adminuser\network"

where

    1) "input.txt" is the model input file
    2) "network" is the network file name (without extension). Upon completion,
       two network graph files will be created: a DOT (file extension .dot) and
       a GML (file extension .gml) file. In this case, two files 'network.dot'
       and 'network.gml' will be created.

Warning

DO NOT supply file extensions for network file name. If you do, ".dot" and ".gml" will be appended to the provided file extension.

Note

Both of the input and network files are in the "C:\Users\adminuser\" folder.

Note

File paths must be enclosed with double quotes, particularly if the file paths contain spaces.

SUMMARY

General commandline options:

    pysawit.py {run|met|net} [-h]

run mode:

    pysawit.py run -i -o [-n] [-e -m[...]] [-h]

met mode:

    pysawit.py met -i -o [-a] [-e -m[...]] [-h]

net mode:

    pysawit.py net -i -o [-e -m[...]] [-h]

Flags -i and -o are required for all modes.
Flags -e and -m are optional but if specified, they must be specified together.

Author - Christopher Teh Boon Sung

printmsg function

printmsg(msg, printtrace=False, wait=False)

Print a list of messages then, if needed, wait for keypress to resume (usually to exit).

Arguments

msg (list): list of messages (str) to print to screen
printtrace (bool): True to print error messages to error log file, else False to suppress
wait (bool): True to wait for Enter key press before exiting, else False to exit immediately

Returns

None:

main function

main()

Main entry point for the program.

Returns

int: Error codes

    0 = no error
    1 = error during model operation (e.g., simulation run) (exception errors)
    2 = error in commandline flags/options