generic/packages/sensitivity.h

/*  ASCEND modelling environment
    Copyright (C) 1990-2006 Carnegie-Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    This file is part of the SLV solver.
*//** @file
    Sensitivity add-on for ASCEND
    by Tom Epperly, Kirk Abbot

    @note This is a static package in ASCEND. It can not be built as a dynamic package
    because it doesn't contain the self-registration stuff.

    This file attempts to implement the extraction of dy_dx from
    a system of equations. If one considers a black-box where x are
    the input variables, u are input parameters, y are the output
    variables, f(x,y,u) is the system of equations that will be solved
    for given x and u, then one can extract the sensitivity information
    of y wrt x.

    One crude but simple way of doing this is to finite-difference the
    given black box, i.e, perturb x, n\subx times by delta x, resolve
    the system of equations at the new value of x, and compute
    dy/dx = (f(x\sub1) - f(x\sub2))/(x\sub1 - x\sub2).
    This is known to be very expensive.

    The solution that will be adopted here is to formulate the Jacobian J of
    the system, (or the system is already solved, to grab the jacobian at
    the solution. Develop the sensitivity matrix df/dx by exact numnerical
    differentiation; this will be a n x n\subx matrix. Compute the LU factors
    for J, and to solve column by column to : LU dz/dx = df/dx. Here
    z, represents all the internal variables to the system and the strictly
    output variables y. In other words J = df/dz.

    Given the solution of the above problem we then simply extract the rows
    of dz/dx, that pertain to the y variables that we are interested in;
    this will give us dy/dx.

    @todo Do we really need 2 files called [Ss]ensitivity.[ch]?  Other one is in tcltk.

    @todo Make this self-registering so that it can be compiled as a dlopenable library.
*/

#ifndef ASC_SENSITIVITY_H
#define ASC_SENSITIVITY_H

#include <utilities/ascConfig.h>
#include <compiler/instance_enum.h>
#include <compiler/compiler.h>
#include <general/list.h>
#include <compiler/extfunc.h>

#include <solver/mtx.h>
#include <solver/mtx_basic.h>
#include <solver/mtx_perms.h>
#include <solver/mtx_query.h>
#include <solver/linsol.h>
#include <solver/linsolqr.h>
#include <solver/slv_types.h>
#include <solver/var.h>
#include <solver/rel.h>
#include <solver/discrete.h>
#include <solver/conditional.h>
#include <solver/logrel.h>
#include <solver/bnd.h>
#include <solver/calc.h>
#include <solver/relman.h>
#include <solver/slv_common.h>
#include <solver/slv_stdcalls.h>
#include <solver/system.h>
#include <solver/slv_client.h>


/* ignores: interp, i, whichvar */
extern int do_solve_eval( struct Instance *i, struct gl_list_t *arglist);

/* ignores: interp, i, whichvar */
extern int do_finite_diff_eval( struct Instance *i, struct gl_list_t *arglist);

extern char sensitivity_help[];

/* ignores: interp, i,  */
extern int do_sensitivity_eval_all( struct Instance *i, struct gl_list_t *arglist);

/* ignores: interp, i,  */
extern int do_sensitivity_eval( struct Instance *i, struct gl_list_t *arglist);

ASC_DLLSPEC(int) sensitivity_register(void);

/*--------------------------------------------------
    The following functions are provided only for use by BLSODE. We want to
    phase this out and replace with a new solver like IDA.
*/
int Compute_J(slv_system_t sys);
int NumberFreeVars(slv_system_t sys);
int NumberIncludedRels(slv_system_t sys);
int LUFactorJacobian(slv_system_t sys);

#endif  /* ASC_SENSITIVITY_H */

1	/* ASCEND modelling environment
2	Copyright (C) 1990-2006 Carnegie-Mellon University
3
4	This program is free software; you can redistribute it and/or modify
5	it under the terms of the GNU General Public License as published by
6	the Free Software Foundation; either version 2 of the License, or
7	(at your option) any later version.
8
9	This program is distributed in the hope that it will be useful,
10	but WITHOUT ANY WARRANTY; without even the implied warranty of
11	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12	GNU General Public License for more details.
13
14	You should have received a copy of the GNU General Public License
15	along with this program; if not, write to the Free Software
16	Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
17	This file is part of the SLV solver.
18	//* @file
19	Sensitivity add-on for ASCEND
20	by Tom Epperly, Kirk Abbot
21
22	@note This is a static package in ASCEND. It can not be built as a dynamic package
23	because it doesn't contain the self-registration stuff.
24
25	This file attempts to implement the extraction of dy_dx from
26	a system of equations. If one considers a black-box where x are
27	the input variables, u are input parameters, y are the output
28	variables, f(x,y,u) is the system of equations that will be solved
29	for given x and u, then one can extract the sensitivity information
30	of y wrt x.
31
32	One crude but simple way of doing this is to finite-difference the
33	given black box, i.e, perturb x, n\subx times by delta x, resolve
34	the system of equations at the new value of x, and compute
35	dy/dx = (f(x\sub1) - f(x\sub2))/(x\sub1 - x\sub2).
36	This is known to be very expensive.
37
38	The solution that will be adopted here is to formulate the Jacobian J of
39	the system, (or the system is already solved, to grab the jacobian at
40	the solution. Develop the sensitivity matrix df/dx by exact numnerical
41	differentiation; this will be a n x n\subx matrix. Compute the LU factors
42	for J, and to solve column by column to : LU dz/dx = df/dx. Here
43	z, represents all the internal variables to the system and the strictly
44	output variables y. In other words J = df/dz.
45
46	Given the solution of the above problem we then simply extract the rows
47	of dz/dx, that pertain to the y variables that we are interested in;
48	this will give us dy/dx.
49
50	@todo Do we really need 2 files called [Ss]ensitivity.[ch]? Other one is in tcltk.
51
52	@todo Make this self-registering so that it can be compiled as a dlopenable library.
53	*/
54
55	#ifndef ASC_SENSITIVITY_H
56	#define ASC_SENSITIVITY_H
57
58	#include <utilities/ascConfig.h>
59	#include <compiler/instance_enum.h>
60	#include <compiler/compiler.h>
61	#include <general/list.h>
62	#include <compiler/extfunc.h>
63
64	#include <solver/mtx.h>
65	#include <solver/mtx_basic.h>
66	#include <solver/mtx_perms.h>
67	#include <solver/mtx_query.h>
68	#include <solver/linsol.h>
69	#include <solver/linsolqr.h>
70	#include <solver/slv_types.h>
71	#include <solver/var.h>
72	#include <solver/rel.h>
73	#include <solver/discrete.h>
74	#include <solver/conditional.h>
75	#include <solver/logrel.h>
76	#include <solver/bnd.h>
77	#include <solver/calc.h>
78	#include <solver/relman.h>
79	#include <solver/slv_common.h>
80	#include <solver/slv_stdcalls.h>
81	#include <solver/system.h>
82	#include <solver/slv_client.h>
83
84
85	/* ignores: interp, i, whichvar */
86	extern int do_solve_eval( struct Instance i, struct gl_list_t arglist);
87
88	/* ignores: interp, i, whichvar */
89	extern int do_finite_diff_eval( struct Instance i, struct gl_list_t arglist);
90
91	extern char sensitivity_help[];
92
93	/* ignores: interp, i, */
94	extern int do_sensitivity_eval_all( struct Instance i, struct gl_list_t arglist);
95
96	/* ignores: interp, i, */
97	extern int do_sensitivity_eval( struct Instance i, struct gl_list_t arglist);
98
99	ASC_DLLSPEC(int) sensitivity_register(void);
100
101	/*--------------------------------------------------
102	The following functions are provided only for use by BLSODE. We want to
103	phase this out and replace with a new solver like IDA.
104	*/
105	int Compute_J(slv_system_t sys);
106	int NumberFreeVars(slv_system_t sys);
107	int NumberIncludedRels(slv_system_t sys);
108	int LUFactorJacobian(slv_system_t sys);
109
110	#endif /* ASC_SENSITIVITY_H */
111