The Jacaranda system user's guide

Table of Contents

Introduction

Jacaranda is a decision support system for computer-aided design. It aims to support the engineer in the generation and selection of alternative process configurations for complex problems in design. It also provides a generic modelling framework with support for data analysis and visualisation interfaces for some aspects of design.

Jacaranda is implemented as an object oriented framework. This framework provides a number of algorithmic techniques for automated design (process synthesis), including support for simulation and optimisation. Jacaranda is implemented in the Java language. The key technology is implicit enumeration for simultaneously generating and searching the space of possible configurations for a given design problem. Jacaranda able to generate process designs with process heat integration for energy demand reduction and with recycle structures. It is also able to handle under-specified problems as they frequently appear in early, conceptual design. Jacaranda is able to address multiple criteria simultaneously in all optimisation aspects.

This document gives an overview of the interface to Jacaranda; emphasis is placed on the use of the Jacaranda system through illustration by example.

Download Jacaranda

An evaluation copy of Jacaranda can be found here: jacaranda-20220826.jar . Please read and follow the licensing instructions before using. Further, if Jacaranda is used, please do let the author know and please cite relevant articles (see bibliography below) in any resulting publications. Feedback, including bug reports, is most welcome.

Expressions

Jacaranda provides a vector based modelling language, essentially a highly functional calculator. All variables and expressions in this language are vector based, making it relatively easy to model stream compositions and similar quantities. However, the modelling language does not support the concept of simultaneous equations: it is instead similar to most programming languages such as Matlab or FORTRAN. The modelling system is implemented in the jacaranda.util.expr.Expression class. In the documentation that follows, any reference to expressions is a reference to this modelling language.

Using Jacaranda

The main interface for the Jacaranda system is based on text input files. Although there is a graphical interface,

jacaranda-gui.png

Figure 1: Graphical interface for the Jacaranda system

this is only a simple interface to either input files or objects previously created using text input files. Therefore, the user of Jacaranda must be able to create text based input files.

Text Based Interface

Jacaranda is started by the command

java jacaranda.Main [options] [input files ...]

which reads in commands from each of the input files given. If not input files are given, the graphical interface, shown above, will be started. For this command to work properly, you will have had to set the CLASSPATH environment variable for Java to find the Jacaranda system. Alternatively, if you have the jar file for the Jacaranda system, you can run Jacaranda as follows:

java -jar jacaranda-YYYYMMDD.jar [options] input files...

where the YYYYMMDD part of the jar file name will be the date of the version of Jacaranda you have.

Command line arguments

The list of available options can be found interactively by giving the -h option alone. Briefly, the options available include:

-b
After the last input file has been processed, bring up a graphical browser which gives access to all objects defined during the processing of the last input file. It should be noted at this point that the system has been written with the assumption that only one synthesis job will be run for a given java command run.
-d N
Set the debug level to the value N. The default is -1 which simply shows a running total of the number of subproblems encountered during the synthesis search procedure and the number nodes created in the search graph. Higher values give more (very verbose) information typically only useful for the author of this document when debugging his code!
-h
List the options that are available.
-n N
Specify the number of solutions to generate in the synthesis procedure. The default is to generate the best solution only (N=1). Values of N up to about 5 or 10 are reasonable. Note that computer memory use is directly related to this value. Computational time goes up as well but much less slowly for small values of N. N must be strictly greater than 0.
-o filename
Direct all console output to the file whose name is specified. If the filename is window, the output is directed to a graphical window that is created automatically.
-r
Generate an HTML based report of all the objects created in the current run at the end of the run. This will create a sub-directory (sub-folder) whose name is defined by the project name, if given. If no project name is given, the folder name is jacaranda.
-s
At the end of the run, save all existing objects as individual files using the default persistent object store (the default being the directory esfobjects in the user's home directory). Note: make sure this directory exists before using this option!
--soe
Tell the input processor to stop immediately when an error occurs (stop on error). This is particularly useful when writing large input files for complex problems.
-t N
Specify the number of threads to use during the synthesis procedure. This is very experimental and only applies to the symmetric multiprocessing procedures which are currently under development. Only included here for completeness!

The rest of the command line consists of input files which contain commands as described below. At the end of any invocation of Jacaranda which terminates normally (i.e. not interrupted by \C), there is a summary of the run including an indication of any error or warning conditions that may have arisen.

Output

The output from Jacaranda consists of text that can be read either on the console or within the graphical window when using the graphical interface. If re-directed to a file, the format of the output follows the conventions for org-mode, a special outlining mode in the Emacs editor. Although the text is readable without org-mode, using Emacs with org-mode is highly recommended.

Input file commands

There are two types of commands in the input files. The majority of an input file will consist of the definition of new objects. This is described below after a description of some special commands:

define
Enter a mode that allows the user to define new global variables. These variables are available to all unit models through the expression evaluator. The global variables include the definition of measurement units and new ones can be defined. Variables can be made to be constant so that their values cannot be subsequently changed. The following commands are available in this sub-mode:
constant name value comment

Create a new constant variable (I know: a contradiction in terms…) with name and value given. The value may be an expression which is evaluated before assigning its value to the new variable. The comment field is optional. For example,

constant km " 1000*m"

will define the unit km using the predefined variable m which defines the value of a metre.

print
Displays all variables and constants currently defined.
set name value
Set the value of a currently defined variable.
variable name value comment
Define a new variable. This command has the same syntax as the constant command above. The only difference is that the variable that is created can have its value altered afterward definition.
description
Alias for the 'title' command (see below).
input
Read in commands from another file, the name of which is given as an argument to this command.
load
Load an object from persistent store. This command has two versions. The first expects the fully qualified name (excluding the directory) which has the form name.date.user.type. For example, saving a stream called feed will create a persistent object that has a name like feed.19980609195411.ucecesf.stream, where ucecesf happens to be the author's userid. The date is stored in ISO format (concatenation of year, month, day, hours, minutes, and seconds). The second version of this command is easier to use; it expects two arguments. The first argument is the type of object and the second argument is the name. This version will retrieve the most recent instance of an object of the correct type and with the given name, regardless of the user field.
name
Alias for the project command.
project
Give the current project a name (the next word on this input line). This name will be used by the report command (see below). The command name is an alias for this command.
report
Generate an HTML report for the current project. The project name is used to create a new folder (in the folder from which the java command was run) and the contents of all the objects created in this project are exported to this folder. Use your favourite web browser to look at these objects after running Jacaranda.
save
Save all objects as separate files in the currently active directory (the default is objects), which must have been created prior to use of this command. Alternatively, the user may specify given objects to save by listing them on the same line. Each object is stored in a file whose name is automatically created, as described for the load command above.
set
General settings for the input system. The set command enters a new command mode where the following are valid (as in all other command modes, the end command will terminate the mode):
directory
Specify a new location for the persistent object store (see previous section for a description of persistent objects and the associated browser and immediately above for the '-s' option).
print
List out all currently defined settings (in particular, all known unit definitions).
pfmt
Specify the format for text output of pressure values. Default specification is #0.00. The format specification is based on the standard java.text.DecimalFormat. An example is #.0 which means any number of digits before the decimal place, including none, and only one and exactly one after the decimal place.
qfmt
Specify the format for output of duty and energy amounts. See pfmt for format specification. Default value is #0.#.
tfmt
The format for output of temperature values. See above for description of formats for the variable qfmt. Default value is #0.0.
threads
Specifying either true or false indicates whether the system will allow the use of multiple threads when possible. Most users need not worry about this option at this stage.
show
Display the list of all objects created in the input file to this point.
stats
Display some statistics about object creation. This output is only really useful for the developer of the package…
title
Give the title (the rest of this input line) of the project. An alias for this command is description.
use
Specify a directory (actually, a Java class path prefix) to search when the user requests the creation of a new object (see below). This command may be repeated to specify a list of directories to search (one directory per use command).
variables
Alias for the define command.

Other than these special commands, the rest of an input file consists of new object definitions. Each object definition starts with a line which specifies the actual type of object (the Java class) and a unique name to give the object created from that class. Following this line comes a set of zero or more lines which modify the contents of the particular object created and finally a line with end on it alone.

In the guide that follows, input files will either be shown as they should be typed in or, when a sample of the output from Jacaranda is desirable, the input to Jacaranda will be passed directly to Jacaranda for evaluation in the generation of this document. In this latter case, the first line in the example text is actually a directive telling Jacaranda to read in the following input until a line which consists only of EOF on the line. The first example input, below, follows this format.

The following example input creates an instance, which we will name propane, of the jacaranda.design.ps.KistaComponent class which is found in the jacaranda.design.ps package:

java jacaranda.Main --noprompt --noorgmode - << 'EOF'
  jacaranda.design.ps.KistaComponent propane 
    base "45.36/10 * kmol/h"
    bp 230.8 
    cpv -4.224 3.062e-1 -1.586e-4 3.214e-8
    print
  end
EOF

The bp command is specific to the KistaComponent class, the cpv command is specific to the PComponent superclass, and the base command is specific to the Component superclass. Each class has its own set of commands and these are described in the parseLine method every jacaranda.base.EGO object has. The class name has to be a fully qualified Java name including the package hierarchy. The only requirement on the type of object to be created is that it be a sub-class of the jacaranda.base.EGO class. The objects need not be part of the Jacaranda system.

The definition of the base value in the example above illustrates the ability to use previously defined variables. The values of kmol and h are previously defined; other variables, defined by the user, could have been used in this example.

To make typing in the commands easier, the user can specify default class paths to use when looking for the classes to create new objects. This is done using the use command. The example given above could be re-written as follows:

use jacaranda.design.ps        # specify class path directory
KistaComponent propane 
  base "45.36/10 * kmol/h"
  bp 230.8 
  cpv -4.224 3.062e-1 -1.586e-4 3.214e-8
end

Process unit model variables

Interaction with the unit models is handled through the unit variables associated with each unit model. The list of unit variables for any unit model can be listed using an input file of the following form:

java jacaranda.Main --noprompt - << 'EOF'
  jacaranda.design.units.vle.Distillation dist
    print
  end
EOF

where, of course, the first line of the sample input should be replaced by the actual class for the unit model of interest.

The unit variables that can be modified by the user in an input file are those listed under General Unit Settings. The Unit Design Specifications may also be modified. The latter will be used by the Jacaranda synthesis procedure for generating unit design alternatives.

Unit variables are given new values by specifying the type of variable and the name of the variable followed (on the same line) by the value and optionally information describing the discretization parameters for the variable. Only variables which he unit model knows can be given new values. The commands above show how to find the list of variables that the unit recognizes. The type of variable must be consistent with the type expected by the unit model. For instance, if the unit model expects the particular variable to be a real number, then only types which generate real values can be used (e.g. Real, LogReal and RealSet).

The following input defines two unit variables as well as the equations used to evaluate the model after the design method has been successfully applied:

use jacaranda.design.units.vle
Distillation dist
  model
    V = 0.761*sqrt(1/P)
    diam = sqrt( 4*( 0.621*(1+RR)*D*sqrt($(mw*y)/(P/8.314/Tdd))) / Pi)
    height = 0.7 * ns
    colcost = msindex/280 * 101.9 * (diam/0.3)^1.066 * (height/0.3)^0.802 * 5.48
    traycost = msindex/280 * 4.7 * (diam/0.3)^1.55 * (height/0.3) * 2.7
    instrcost = 0
    maintcost = 0
    capcost = colcost+traycost+instrcost
    opercost = maintcost
  end
  LogReal    P  1 10 5
  Real       rec  0.98 0.98 1
  print
end

The distillation unit model (in fact, all unit models) expects the model to be a set of equations evaluated sequentially. The equations can make use of variables defined earlier in the input file and variables which the unit itself defines. All real valued unit variables are automatically mirrored by expression variables. For instance, the model equations listed above make reference to the P variable (the operating pressure).

In the expression given in the example, the capital and operating costs are defined by calculating the velocity of the vapour in the column and the diameter and the height of the column. The expression makes reference to example-defined variables, such as the msindex variable, a global variable defined by the system (but which can be altered by the user) and variables such as RR and D which are defined by the unit itself.

The first unit variable, P, is meant to be a real valued variable. The LogReal type defines a set of values uniformly discretized, on a log basis, between 1 and 10 atm. There are five values in the set. Finally, the recovery (rec) variable is given just one value. The operating pressure could have been specified as a Real variable or even a RealSet variable. The latter is particularly useful when one wishes to consider a diverse set of values for a particular variable. For instance, we may wish to have the synthesis procedure consider the design of distillation units with both low and high recoveries of the key components:

use jacaranda.design.units.vle
Distillation dist
  LogReal    P    1 10 5
  RealSet    rec  0.98 0.999  # consider two different recoveries
end

Please note that the use command must be used so that the input parser can find the definition of the different unit variables. In particular, if the unit variable types are to be the standard ones in the package, the line

use jacaranda.design.units.vle

will be required somewhere above the definition of the units.

New unit variables can also be defined using the new command. The syntax for this command is:

new TYPE DESCRIPTION SingleLineDefinition

where TYPE is one or more of input, specification, tunable, and continuation, concatenated with plus signs. The DESCRIPTION is a general description of the variable in double quotes, and SingleLineDefinition corresponds to the syntax described above for single line re-definitions of existing variables. A full example could look like:

new continuation "Continuation variable for optimization" Real theta 1

Units of measure

As described above, the user can define new variables which may include new unit types. However, all values are stored internally and displayed to the user using the following set of units:

Quantity Units
flow kmol/s
energy kJ
length m
mass kg
power kW
pressure atm
temperature K
time s

All output is based on these units (unless otherwise specified). Input, if not qualified, is also assumed to be in these units. However, all input can be given with units, as shown in the examples in this document. If units are to be given, the expression must be quoted and an operator (* or /) must precede the units specified (this is a feature of the expression evaluator used to parse the user's input). The following is a list of known units for conversion (the full list can be displayed using the print command within the variables sub-mode described at the start of this section): kmol, kg, kJ, kW, s, atm, m, K, mol, g, lb, hr, R (for Rankin), bar, Pa, kPa, J, W, MW, GW, MJ, and GJ. Note that case is significant.

Examples

Instead of attempting to describe fully all the capabilities of Jacaranda, this guide will illustrate the main features through a series of examples. It is expected that any use of Jacaranda beyond some of the directly supported applications will be done in conjunction with the author of Jacaranda.

General modelling and optimisation

Although the aim of Jacaranda is the development and provision of special targeted optimisation procedures for procecapabilitieshe underlying system in Jacaranda must provide some generic support for general optimisation. This generic support is automatically available to users and so it is instructive to illustrate these basic optimisation capabilities of the system.

The input file, minlp.in, in the examples directory presents the model and solution of a problem presented by Westerlund & Westerlund at the ICheap 6 conference in 2003. This is a simple MINLP problem with 1 continuous variable, 1 integer variable and a dis-joint domain of feasibility.

\begin{align*}
 \min_{x,y} z &amp; = 3y - 5x \\
 \mbox{s.t.} \\
 g(x) &amp; \le 0 \\
 x &amp; \in [1,6] \\
 y &amp; \in [1,6] \\
\end{align*}

where

\begin{equation*}
    g(x) = \left [ \begin{array}{c} 2y+3x-24 \\ 3x-2y-8 \\ 2y^2-2\sqrt{y}+11y+8x-39-2\sqrt{x}y^2 \end{array} \right ] 
\end{equation*}
1

A simple variable based encoded genetic algorithm is used to solve this problem, obtaining an optimal value of -13.082 approximately with \(x=3.22\) and \(y=1\).

minlp-example-output-screenshot.png

Figure 2: Output file in Emacs org-mode for MINLP example

Heat exchanger network design using visualisation and user interaction

The input file, hen-10sp1.in, defines a heat exchanger network (HEN) design problem from the literature, 10SP1. This is a problem consisting of 5 cold streams and 5 hot streams with the choice of two utilities, cold water and steam. In Jacaranda, this problem can be solved directly using a number of automated search methods or it can be solved in conjunction with the user of Jacaranda. The latter approach is illustrated by this input file.

hen-gui-explained.png

Figure 3: Annotated view of the heat exchanger network user interaction display in Jacaranda.

A visualisation and user interaction interface is defined which allows the user to manipulate the hot and cold streams directly. The manipulation is through movement in the horizontal direction. Any hot stream, indicated as a red line in the display, which lies directly above a cold stream, a blue line, is considered to define process integration. That is, the excess heat from the particular hot stream will be used to meet some or all of the heating demands of the cold stream.

hen-example-output-screenshot.png

Figure 4: Output file for HEN user interaction example (in Emacs org-mode).

The graphical interface provides access to embedded optimisation methods. In particular, by default a simulated annealing procedure will be invoked when either of the Full or Tune options are selection from the Optimize menu. The only difference in these options is the duration of the search with the latter being a rather short attempt to improve the current solution and the former a more exhaustive search.

hen-example-optimum.png

Figure 5: A good solution obtained using both embedded optimisation and user interaction

Separation sequence synthesis

This example is the design of a complete process configuration with no a priori structural information. The example is based on the problem described by Rathore et al. (1974).

The problem is to generate a sequence of distillation columns to separate a five component feed into pure component streams. All the columns in this example run at the same pressure (6.8 atm). Discrete heating and cooling utilities are available and both capital and operating costs are included in the objective function. In fact, three criteria are specified for solution ranking: one based purely on capital cost, one on operating cost alone, and the third providing an annualized cost based on a 2.5 year amortization period. The best solution for each different criterion is generated.

rathore-example-output-screenshot.png

Figure 6: Output generated for the separation sequence synthesis example (in Emacs org-mode).

This example is described in greater detail in the next section below.

Further examples

Some other example input files are included as part of the standard distribution:

penicillin.in
This example, the generation of a process for the production of penicillin, was described in detail by Steffens et al. (1999a). This example uses a completely different set of stream and unit classes from the VLE type of entities used in the other examples. The class definitions for the bioprocessing objects are also found in a different hierarchy which is not fully documented at this stage. If you have questions about this example, please email Professor E S Fraga.
rathore_hen.in
Similar example to the previous one except for two aspects: the columns are allowed to operate within a range of pressures defined to be from 1 to 32 atm and the system generates a heat integrated sequence. This problem takes significantly longer to run than the previous problem but arguably generates better designs.
reaction-with-purge.in
A purely conceptual level reaction-separation problem with pseudo-components (fixed constant physical properties) with a purge unit available.
simple-flowsheet.in
Simple example showing how a flowsheet can be defined directly in the system, skipping the synthesis procedures completely. This is useful for accessing the stochastic nonlinear optimization procedures in Jacaranda.

References

The following are some of the articles referenced in this document. A full list of the author's publications can be found on his web site.

  • E S Fraga (1996), Discrete optimization using string encodings for the synthesis of complete chemical processes, in State of the Art in Global Optimization: Computational Methods & Applications, C A Floudas & P M Pardalos, Editors, 627-651.
  • E S Fraga (1998), The generation and use of partial solutions for process synthesis, Chemical Engineering Research Design 76:45-54.
  • E S Fraga & K I M McKinnon (1994), CHiPS: A process synthesis package, Chemical Engineering Research Design 72:389-394.
  • E S Fraga, R Patel & G W A Rowe (2001), A visual representation of process heat exchange as a basis for user interaction and stochastic optimization. Chemical Engineering Research & Design 79:765-776.
  • E S Fraga, M A Steffens, I D L Bogle & A K Hind (2000), An object oriented framework for process design and optimization, in M F Malone, J A Trainham & B Carnahan (editors), Foundations of Computer-Aided Process Design, AIChE Symposium Series 323:446-449.
  • E S Fraga & A Zilinskas (2002), Evaluation of hybrid optimization methods for the optimal design of heat integrated distillation sequences, Advances in Engineering Software, Advances in Engineering Software 34:73-86, DOI: 10.1016/S0965-9978(02)00125-4.
  • D M Laing & E S Fraga (1997), A case study on synthesis in preliminary design, Computers & Chemical Engineering 21:S53-S58.
  • W. Morton (2002), Optimisation of a heat exchanger network superstructure using nonlinear programming, Proc. Inst. Mech. Eng. Part E 216:89-104.
  • R N S Rathore, K A van Wormer, & G J Powers (1974), Synthesis strategies for multicomponent separation systems with energy integration, AIChE J 20:491–502.
  • R N S Rathore, K A van Wormer, & G J Powers (1974), Synthesis of distillation systems with energy integration, AIChE J 20:940–950.
  • M A Steffens, E S Fraga & I D L Bogle (1999a), Multicriteria process synthesis for generating sustainable and economic bioprocesses. Computers & Chemical Engineering 23:1455-1467.
  • M A Steffens, E S Fraga & I D L Bogle (1999b), Optimal system wide design for bioprocesses, Computers & Chemical Engineering 23:S51-S54.
  • M A Steffens, E S Fraga & I D L Bogle (2000), Synthesis of downstream purification processes using physical properties data. Biotechnology & Bioengineering 68:218-230.

Recent change history

2022-08-26 13:27 typographical error in bibliography
2022-07-18 13:12 fix link for licensing and updated Jacaranda jar file
2022-07-18 13:03 preparing for release of nature inspired optimization book
2017-09-22 15:30 minor changes to file management for the user's guide
2016-09-12 08:34 fixed underscore in file name for rathore HEN example link
2016-09-12 08:32 updated licensing information and guidance
2016-09-12 08:27 updated links and added link to licensing
2016-09-11 15:19 changed title of user's guide to be more precise
2016-09-11 15:08 provided link to downloadable version of Jacaranda
2016-09-09 08:24 updated hybrid optimisation paper reference
2016-09-09 08:22 fixed volume references in publication list in user's guide
2016-09-09 08:20 added recent change log to the user's guide
2016-09-09 08:13 added filter for turning wrap off in textarea HTML blocks
2016-09-08 19:25 started cleaning up and updating the user's guide
2009-11-17 22:24 documentation: added CSS settings for examples/code
2009-11-11 15:11 documentation: completed trimmed down manual with three examples
2009-11-10 17:40 output: further org-mode consistency tweaks
2009-11-09 14:33 documentation: further work on text interface section of guide
2009-11-03 15:26 documentation: cleaning up the whole document, making it simpler to read
2009-11-03 11:25 documentation: started rewriting from the top down

Date: 2022.08.26 13:23:55

Author: Professor Eric S Fraga, Sargent Centre for Process Systems Engineering, Department of Chemical Engineering, UCL

Created: 2022-08-26 Fri 13:27

Validate