ASCEND - User contributions [en]

Global variables

2012-07-06T18:41:02Z

BenAllan: /* The object lives in ascend, and a design for global use reduction */

{{task}}

We would like to get rid of the current use of global variables in ASCEND, so that we can start to think about using ASCEND in multithreaded and/or embedded ways. This page will report any cases of global variables that we have found, and perhaps some discussion about how we can best eliminate them. Not all cases will be the same. Globals make some aspects of code reading easier (not crowding C arg lists with context pointers) and some harder: when complex side effects are in play. We try hard to avoid any usage of globals with complex side effects.

== Ways for removing global variables ==

A number of options exist:

* keeping them. This is appropriate in a very limited set of situations, such as for data that has been loaded from a configuration file when the program started.
* groupin them into a top-level data structure. We imagine structures like "library", "simulation" and "system" could be created that could hold most global variables.
* passing them. Where global variables have been used as a convenience to avoid having to expand function parameter lists, we can just change to passing them as parameters.
* converting them to #defines. May be appropriate for certain constants.
* converting them to thread-local variables (may need to assess implication for embedded applications)
* adding mutex constraints (so that they can only be accessed once at a time)
* migrating them to another code layer, eg into the GUI (this has already been done in some cases)

== Particular kinds of usage and what can be done about it ==

* Lex/Yacc C based scanners and parsers (and some still current versions of GNU bison/flex) generate code full of globals and non-threadsafe functions. It's not our job to fix this. The 'safe' thing to do is put a mutex around the parse function.
* ASCEND defined parser context flags, once properly identified, can remain global because the mutex for yacc will also protect them. Cosmetically, the 'properly identified' problem could be resolved by collecting these variables into a single well-named struct g_parser_context.
* Type library globals: most of these should be moved into a formal struct ascUniverse. More about that below.
* Instantiator tuning: most of these should be moved into a struct ascCompilerTuning.
* Memory recycle pools of small objects, tied to globals. These are tied to globals (typically file-scope static variables hidden behind allocator functions) to avoid passing pool pointers everywhere. In solvers like linsolqr, these pools should be tied to major objects instead of file global. "Too many pool objects, too short lived" is a problem that can be solved (taking mtx as an example, perhaps) by maintaining a list of idle mtx element pools; when to clear the idle pools is a minor problem. In the compiler, many pools should come and go with their Universe or with the destruction of the ascend type list and all dependent instances.

== The object lives in ascend, and a design for global use reduction ==
The most basic facts: ascend parses a set of type definitions into a self-consistent class hierarchy. These type definitions can then be used with the instantiator to create model instances with relation and variable data. These instance objects answer many queries by accessing pointers to the type definitions used to create the objects. ASCEND has a concept named UNIVERSAL (not unlike globals in C) whereby for a given type definition, only one instance will ever be constructed. Both types and instances are deeply tied to a symbol (constant strings) table. Throughout ascend, both types and symbols are heavily compared for identity by comparing pointers.

Key outcome of the above: if we wrap all the compiler globals in a context object of universal scope, we can then have at a higher (scripting) level multiple universe objects. **Objects from distinct universes cannot be compared except in string form** !

Given the above, then, ascend model type and instance data can be organized into something like the following. I will use c++ notation, but the implementation will be C. When in the parser, a single global (the universe pointer for the parsing to operate within) is needed and a mutex.
<source lang="c">
class ascUniverse {
public:
// functions only
private:
int auid; // serial number of this universe
struct ascUniverse *next;
// struct Symtab symtab;
// memory pools for statement, vlist, etc, etc
// struct Simlist simlist;
// struct Library library
// etc
static struct ascUniverse * g_universe_list;
};
</source>

Many parts within the compiler will need only a pointer to the piece of the universe where their data lives; we should not be passing universe pointers everywhere in the compiler. Implementing all this correctly as a refactorization is extremely tedious and should only be done with a test suite and automated refactoring tools.

== Global variables in libascend.so ==

The main place where global variables are a problem for ASCEND is in <tt>libascend</tt>, our core library include the ASCEND parser/compiler and evaluation routines, but '''hopefully''' excluding the solvers.

Below is a list of globals generated using GNU <tt>nm</tt>.

<source lang="sh">john@thunder:~/ascend$ nm libascend.so | grep -i " [DdGgSsBb] ";
001828a0 b AllowedContents
00926420 b BracesNestLevel
0092889c b CmpEv
0092641c b CommentNestLevel
00180be0 d DimNames
00927ac8 b EvaluatingSets
00926548 b FundamentalTypeList
00928528 b GlobalUniversalTable
00927c14 b InterfaceNotify
00927c0c b InterfacePtrATS
00927c10 b InterfacePtrDelete
00928790 b L.6247
0092879c b L.6717
0092bca0 b LibraryHashTable
00927ac4 b ListMode
00926424 b MatchedBackslash
00927a64 b MinusOne
00927a84 b One
001820c0 b RecycledContents
001818e0 b RecycledList
00926428 b RequireIndex
00926460 b RequireStack
009286e0 B Solv_C_CheckHalt_Flag
00927aa4 b Three
00927a94 b Two
001816a0 d VpTable
009300dc b X
00927a74 b Zero
0017fcc0 d __CTOR_END__
0017fcbc d __CTOR_LIST__
0017fcc8 d __DTOR_END__
0017fcc4 d __DTOR_LIST__
0017fccc d __JCR_END__
0017fccc d __JCR_LIST__
00180a20 d __dso_handle
00181811 d blockend
001817fc d blockmagic
001814fc D calc_ok
00181500 d calc_print_errors
00928338 b cap.11161
009286d8 b cap.7377
00181520 d commands
001818a0 b completed.6625
009300e0 b conopt_fptrs
00927a54 b constants_inited
001817d0 d csdata
00183088 b dcps.2434
00926488 b default_library_path.7912
0092648c b default_solvers_path.7911
0018167c d defaultintegrators.6720
00927a60 b deriv_store.5961
00926564 b done.4160
00183090 b dref.2433
00927c80 b ds.3670
00927d60 b ds.4078
00928540 b ds.4252
00928060 b ds.4837
00928140 b ds.5578
001818a4 b dtor_idx.6627
009287c8 b elt.4095
009287cc b elt.4148
00926430 b errcount.6732
009263a4 b errcount.8155
00181670 d errname.6760
00928384 b error_statement_sym.4928
00928800 b exception_buffer
009287e0 b exception_status
00180a24 d f_first
00180a28 d f_fpe_top_of_stack
00926364 b f_fpe_traps
00180a2c d f_int_top_of_stack
00926368 b f_int_traps
001830e0 b f_mem_rec
001830c8 b f_memory_allocated
001830c4 b f_memory_length
001830c0 b f_memory_log_file
009242e0 b f_panic_callback_func
001830cc b f_peak_memory_usage
00180a30 d f_seg_top_of_stack
0092636c b f_seg_traps
00925300 b g_Asc_printVtables
00927acc b g_DeclarativeContext
00181320 d g_DefinitionErrorMessages
00927abc b g_EvaluationContext
00927ac0 b g_EvaluationForTable
00927ab8 b g_ExtVariablesTable
00927ab4 b g_ExternalFuncLibrary
00928018 b g_ExternalNodeStamps
00180e60 d g_abs_f
001812b0 D g_alt_ending
00926490 b g_ammarking
00180f20 d g_arccos_f
001810a0 d g_arccosh_f
00180ee0 d g_arcsin_f
00181060 d g_arcsinh_f
00180f60 d g_arctan_f
001810e0 d g_arctanh_f
00926494 b g_array_child_pool
00928444 b g_array_desc_count
00928448 b g_array_desc_list
0018309c b g_ascend_dllist
009264c0 b g_atom_bytes
009263b0 b g_atom_dim_ptr
0092bc50 b g_b_inst
0018187c d g_ba_elimdata
0092bc6c b g_ba_inst
0092863c b g_bad_rel_in_list
0092bc7c b g_bc_inst
00928434 b g_big_strings
00928438 b g_big_strings_cnt
00928640 b g_blockmethod
00180a60 d g_bt_data
00926398 b g_callargs
0092864c b g_case_number
00928030 b g_cbbccount
0092802c b g_cbbdcount
00181160 d g_cbrt_f
001812ec D g_check_dimensions_noisy
00926514 b g_clique_list
00181208 D g_compiler_counter
00928360 B g_compiler_timing
00180a34 D g_compiler_warnings
0092649c b g_cons
009263a0 b g_constant_type
009279d4 b g_copy_numnodes
00180d60 d g_cos_f
00180fe0 d g_cosh_f
00181120 d g_cube_f
00927f54 b g_current_module
0092bc48 b g_cursim
00926544 b g_def_child_bit_list
00926540 b g_def_child_desc_ptr
0092653c b g_def_child_list_ptr
009263b4 b g_default_dim_ptr
009263b8 b g_default_double
009263c0 b g_default_long
00928b4c b g_default_symbol
009263a8 b g_defaulted
00926534 b g_diagf
009263ac b g_dim_ptr
0092ac38 B g_dimen_list
0092ac30 b g_dimensionless
009286b4 b g_dis_tag
009284c0 b g_drt_depth
00927c28 b g_dummy_type
0092ac40 b g_dump_ht
0092bc40 b g_dump_inst_count
0092bc44 b g_dump_type_count
00926384 b g_end_identifier
001830a0 b g_env_list
00925340 b g_error_reporter_cache
00925328 b g_error_reporter_callback
00925320 b g_error_reporter_tree
00925324 b g_error_reporter_tree_current
00180c20 d g_exp_f
00927a50 b g_exprs_pool
00927c34 b g_externalmodel_type
009264fc b g_extra_parents
00926500 b g_extra_parents_sum
009264f8 b g_extra_paths
009288a0 b g_foreign_code_call_env
00927ad0 b g_forvar_recycle_list
00927ad4 b g_forvarfile
009289e0 B g_fpe_env
00927ad8 b g_free_store
001811a0 d g_func_list
00926370 b g_header_linenum
00180ea0 d g_hold_f
0092bc5c b g_i_inst
0092bc74 b g_ia_inst
0092bc60 b g_ic_inst
0017fce0 d g_instancetypenames
0018120c d g_instantiate_relns
00928a80 B g_int_env
001814f8 d g_iscomplete
0092844c b g_it_dummy_enum
00181310 d g_it_dummy_int
00927c00 b g_iteration
009284a8 b g_lcl_head
009284b8 b g_lcl_length
009284b4 b g_lcl_pivot
009284b0 b g_lcl_recycle
009284ac b g_lcl_tail
009284bc b g_lclrecycle_length
00181740 D g_linsolqr_timing
001818c0 b g_list_head_pool
00180c60 d g_ln_f
00180c08 D g_lnm_epsilon
00180ca0 d g_lnm_f
00180ce0 d g_log10_f
00927e40 b g_log_shortbuf
00927d54 b g_logrel_stack
00927c24 b g_logrel_type
00927f44 b g_logrelation_bvar_list
00927f48 b g_logrelation_satrel_list
00927f50 b g_logterm_pool
00181288 d g_logterm_ptrs
00927e34 b g_logwritfp
0092bc54 b g_lrel_inst
0092650c b g_maximum_children
009264f4 b g_maximum_parents
00926520 b g_maximum_relations
00926508 b g_minimum_children
009264f0 b g_minimum_parents
0092651c b g_minimum_relations
00926560 b g_missing
0092bc88 b g_mod_inst
009264b8 b g_model_bytes
00928000 b g_model_definition_methods
00926388 b g_model_parameters
00927f5c b g_module_list
00181220 d g_mpi_message
009287c4 b g_mtx_debug_redirect
0018185c d g_mtx_null_col_vector_data
0018181c d g_mtx_null_index_data
0018183c d g_mtx_null_mark_data
0018186c d g_mtx_null_row_vector_data
0018182c d g_mtx_null_sum_data
0018184c d g_mtx_null_vector_data
009301b4 b g_mtxerr
00927f6c b g_name_pool
009279e0 b g_names_needed
00927a58 b g_new_var_list
0092639c b g_notelist
00927f70 b g_notes_data_base
009264e8 b g_num_array_instances
009264dc b g_num_atom_children
009264bc b g_num_atom_instances
009264b0 b g_num_complex_instances
009264d8 b g_num_constant_all
009264cc b g_num_constant_bool
009264d0 b g_num_constant_int
009264c8 b g_num_constant_real
009264d4 b g_num_constant_sym
009264b4 b g_num_model_instances
00927f64 b g_num_names_cur
00927f68 b g_num_names_max
009264e0 b g_num_relation_instances
009264ec b g_num_unsel_instances
009284a4 b g_number
00927f90 b g_numlist_head_pool
00924300 b g_panic_outfile
00926390 b g_parameter_reduction
0092638c b g_parameter_wheres
0018130c d g_parse_count
00180a38 d g_parse_relns
009284c4 B g_parser_warnings
00927f9c b g_pending_count
00927fa0 b g_pending_list
00927fa4 b g_pending_list_end
00927fa8 b g_pending_pool
0092cca0 B g_plot_type
00927f94 b g_ppe_pool
001811fc d g_proc
00926378 b g_proc_name
00928004 b g_procframe_stop
00928008 b g_proto_count
0092ccc0 b g_proto_ht
0092bc94 b g_r_inst
0092bc78 b g_ra_inst
0092bc64 b g_rc_inst
00927a00 b g_recycle_expreval_stacks
00927f84 b g_recycled_npl
00926380 b g_refines_name
0092bc84 b g_rel_inst
00928040 b g_rel_stack
00928044 b g_rel_stack_pool
009264e4 b g_relation_guts
0092652c b g_relation_terms
00927c20 b g_relation_type
00928014 b g_relation_var_list
00928010 B g_relative_inst
00928618 b g_reuse
009286c4 b g_reuse
0092bc58 b g_s_inst
0092bc80 b g_sa_inst
0092bc90 b g_sc_inst
0092800c B g_search_inst
00928940 B g_seg_env
00928354 b g_set_pool
00927c30 b g_set_type
00928358 b g_sets_pool
00928220 b g_shortbuf
001812f4 d g_show_statement_detail
00927f4c b g_simplify_logrelations
001812cc D g_simplify_relations
0092835c B g_simulation_list
00180d20 d g_sin_f
00180fa0 d g_sinh_f
00927f60 b g_sldestroy
0092877c b g_solver_binary_type
009286c0 b g_solver_dis_type
00928778 b g_solver_int_type
00928780 b g_solver_semi_type
00928774 b g_solver_var_type
00180de0 d g_sqr_f
00180e20 d g_sqrt_f
00928414 b g_statio_flowtypenames
001812f8 d g_statio_label
009283a0 b g_statio_stattypenames
00928380 b g_statio_suppressions
00927b00 b g_string_buffer
00927f58 b g_string_modules_processed
00928428 b g_string_space
00927fc0 b g_strings
00928624 b g_strings
009286b8 b g_strings
009286d0 b g_strings
009286d4 b g_strings
00928758 b g_strings
00926498 b g_suppressions
0092bc8c b g_sym_inst
0092bc4c b g_syma_inst
00928430 b g_symbol_collisions
0092842c b g_symbol_size
0092dcc0 b g_symbol_table
00928614 b g_symbol_values_list
00927c40 b g_symbols
00928460 b g_symbols
009287ac b g_symbols
0092bc68 b g_symc_inst
00180da0 d g_tan_f
00181020 d g_tanh_f
0092843c b g_temporary_var_list
00928440 b g_temporary_var_recycle
0092801c b g_term_pool
001812d0 d g_term_ptrs
009284c8 b g_tlibs_depth
0092ab80 b g_token_counts
00926530 b g_total_array_children
00926510 b g_total_children
00926504 b g_total_parents
00926528 b g_total_reals_in_rels
00926524 b g_total_relations
00926518 b g_total_variables
009264c4 b g_tree_bytes
0092ac34 b g_trig_dimen
00927c04 b g_trychildexpansion_errmessage
009264ac b g_type_count_list
0092637c b g_type_name
00926394 b g_typeargs
00927c08 b g_unasscon_count
00928500 b g_unit_base_name
009284f0 b g_unit_explain_error_strings
00927adc b g_units_alloc
009284ec b g_units_collisions
001814c0 d g_units_errors.4640
0092f0e0 B g_units_hash_table
0092ecc0 b g_units_id_space
009263c4 b g_units_ptr
009284e8 b g_units_size
009284e0 b g_units_str
009284e4 b g_units_str_len
00927f98 b g_unresolved_count
00926374 b g_untrapped_error
00181204 D g_use_copyanon
0092852c b g_value_pool
00928754 b g_var_tag
0092bc70 b g_when_inst
00927c2c b g_when_type
0092ac3c b g_wild_dimen
0092642c b g_workbuf
00180a44 d g_workbuf_len.6555
00928214 b g_writfp
00928348 b glob_done
00927f40 b glob_lrel
00928340 b glob_rel
00928344 b glob_varnum
009279d0 b global_command_list
00928530 b global_visit_num
009287bc b hhrowlist.6528
00183074 b i.2578
00926354 b i.2755
00927ae0 b importhandler_library
00927ae4 b importhandler_sharedpointers
00926538 b init.5484
00928794 b init.6246
009287a0 b init.6716
0092878c b inst
009287c0 b last_value_matrix
00928798 b lastsolver.6445
00928330 b lhscap.9848
009287b8 b listlen.6529
00928784 b loaded.3887
00180ba0 d metadata.4158
001817e0 d mtxmagic
00928700 b name.6123
00928660 b name.6164
00181744 d names.4315
00181760 d names.4320
0018307c b newsize.2576
0092635c b newsize.2753
00181504 d nextid.6241
001812c8 d nostr.4857
00181688 d nrels.7185
0018168c d nrels.7199
009286fc b nuldev.5971
00181690 d nvars.7213
00183080 b oldsize.2575
00926360 b oldsize.2752
001817f2 d permmagic
00928648 b poly.3808
00928350 b poly.3924
00928644 b poly_cap.3809
0092834c b poly_cap.3925
00927a5c b previous_store.5962
0092833c b ptr.11160
009286dc b ptr.7376
00183078 b punt.2577
00926358 b punt.2754
00183098 b ref.2432
00928334 b rel.9847
009287a4 b reported_already.8633
009287a8 b reported_already.8653
00926580 b result.4159
009286e4 b rfilter.7742
0092832c b rhscap.9849
001817c0 d rsdata
001812f0 d safe_print_errors
0017fda0 d slv_reg
00928320 b soln_list.9691
00926418 b start_line
00928534 b stopnum.3912
00181508 d suppress_rel_flag.6780
00928788 b sys
001812a4 d unk.4785
00925304 b use_xterm_color.2533
009286ec b vfilter.7802
009286f4 b vfilter.7892
00928020 b warnexpt.5603
00928028 b warnexpt.5731
00928024 b warnfdiff.5732
009263f4 b yy_buffer_stack
009263f0 b yy_buffer_stack_max
009263ec b yy_buffer_stack_top
009263f8 b yy_c_buf_p
0092643c b yy_did_buffer_switch_on_eof
00926448 b yy_full_lp
00926440 b yy_full_match
0092644c b yy_full_state
00926434 b yy_hold_char
009263fc b yy_init
00180a40 d yy_line
0092640c b yy_looking_for_trail_begin
00926444 b yy_lp
00926410 b yy_more_offset
00926438 b yy_n_chars
00926414 b yy_prev_more_offset
00926400 b yy_start
00926404 b yy_state_buf
00926408 b yy_state_ptr
0092ab64 b yytext_ptr
009263e8 b zz__flex_debug
00928b50 b zz_char
009263e0 b zz_in
0092ab60 b zz_leng
00180a3c d zz_lineno
00928b20 b zz_lval
00928b54 b zz_nerrs
009263e4 b zz_out
00928b60 b zz_text
john@thunder:~/ascend$
</source>

== Static variables ==

Another place where quasi-global variables can occur is as static variables within functions. It needs to be assessed whether the above listing includes those types of variables.

Global variables

2012-07-06T18:30:38Z

BenAllan:

{{task}}

We would like to get rid of the current use of global variables in ASCEND, so that we can start to think about using ASCEND in multithreaded and/or embedded ways. This page will report any cases of global variables that we have found, and perhaps some discussion about how we can best eliminate them. Not all cases will be the same. Globals make some aspects of code reading easier (not crowding C arg lists with context pointers) and some harder: when complex side effects are in play. We try hard to avoid any usage of globals with complex side effects.

== Ways for removing global variables ==

A number of options exist:

* keeping them. This is appropriate in a very limited set of situations, such as for data that has been loaded from a configuration file when the program started.
* groupin them into a top-level data structure. We imagine structures like "library", "simulation" and "system" could be created that could hold most global variables.
* passing them. Where global variables have been used as a convenience to avoid having to expand function parameter lists, we can just change to passing them as parameters.
* converting them to #defines. May be appropriate for certain constants.
* converting them to thread-local variables (may need to assess implication for embedded applications)
* adding mutex constraints (so that they can only be accessed once at a time)
* migrating them to another code layer, eg into the GUI (this has already been done in some cases)

== Particular kinds of usage and what can be done about it ==

* Lex/Yacc C based scanners and parsers (and some still current versions of GNU bison/flex) generate code full of globals and non-threadsafe functions. It's not our job to fix this. The 'safe' thing to do is put a mutex around the parse function.
* ASCEND defined parser context flags, once properly identified, can remain global because the mutex for yacc will also protect them. Cosmetically, the 'properly identified' problem could be resolved by collecting these variables into a single well-named struct g_parser_context.
* Type library globals: most of these should be moved into a formal struct ascUniverse. More about that below.
* Instantiator tuning: most of these should be moved into a struct ascCompilerTuning.
* Memory recycle pools of small objects, tied to globals. These are tied to globals (typically file-scope static variables hidden behind allocator functions) to avoid passing pool pointers everywhere. In solvers like linsolqr, these pools should be tied to major objects instead of file global. "Too many pool objects, too short lived" is a problem that can be solved (taking mtx as an example, perhaps) by maintaining a list of idle mtx element pools; when to clear the idle pools is a minor problem. In the compiler, many pools should come and go with their Universe or with the destruction of the ascend type list and all dependent instances.

== The object lives in ascend, and a design for global use reduction ==
The most basic facts: ascend parses a set of type definitions into a self-consistent class hierarchy. These type definitions can then be used with the instantiator to create model instances with relation and variable data. These instance objects answer many queries by accessing pointers to the type definitions used to create the objects. ASCEND has a concept named UNIVERSAL (not unlike globals in C) whereby for a given type definition, only one instance will ever be constructed. Both types and instances are deeply tied to a symbol (constant strings) table. Throughout ascend, both types and symbols are heavily compared for identity by comparing pointers.

Key outcome of the above: if we wrap all the compiler globals in a context object of universal scope, we can then have at a higher (scripting) level multiple universe objects. *Objects from distinct universes cannot be compared except in string form*!

Given the above, then, ascend model type and instance data can be organized into something like the following. I will use c++ notation, but the implementation will be C.
<source lang="c">
class ascUniverse {
public:
// functions only
private:

};
</source>

== Global variables in libascend.so ==

The main place where global variables are a problem for ASCEND is in <tt>libascend</tt>, our core library include the ASCEND parser/compiler and evaluation routines, but '''hopefully''' excluding the solvers.

Below is a list of globals generated using GNU <tt>nm</tt>.

<source lang="sh">john@thunder:~/ascend$ nm libascend.so | grep -i " [DdGgSsBb] ";
001828a0 b AllowedContents
00926420 b BracesNestLevel
0092889c b CmpEv
0092641c b CommentNestLevel
00180be0 d DimNames
00927ac8 b EvaluatingSets
00926548 b FundamentalTypeList
00928528 b GlobalUniversalTable
00927c14 b InterfaceNotify
00927c0c b InterfacePtrATS
00927c10 b InterfacePtrDelete
00928790 b L.6247
0092879c b L.6717
0092bca0 b LibraryHashTable
00927ac4 b ListMode
00926424 b MatchedBackslash
00927a64 b MinusOne
00927a84 b One
001820c0 b RecycledContents
001818e0 b RecycledList
00926428 b RequireIndex
00926460 b RequireStack
009286e0 B Solv_C_CheckHalt_Flag
00927aa4 b Three
00927a94 b Two
001816a0 d VpTable
009300dc b X
00927a74 b Zero
0017fcc0 d __CTOR_END__
0017fcbc d __CTOR_LIST__
0017fcc8 d __DTOR_END__
0017fcc4 d __DTOR_LIST__
0017fccc d __JCR_END__
0017fccc d __JCR_LIST__
00180a20 d __dso_handle
00181811 d blockend
001817fc d blockmagic
001814fc D calc_ok
00181500 d calc_print_errors
00928338 b cap.11161
009286d8 b cap.7377
00181520 d commands
001818a0 b completed.6625
009300e0 b conopt_fptrs
00927a54 b constants_inited
001817d0 d csdata
00183088 b dcps.2434
00926488 b default_library_path.7912
0092648c b default_solvers_path.7911
0018167c d defaultintegrators.6720
00927a60 b deriv_store.5961
00926564 b done.4160
00183090 b dref.2433
00927c80 b ds.3670
00927d60 b ds.4078
00928540 b ds.4252
00928060 b ds.4837
00928140 b ds.5578
001818a4 b dtor_idx.6627
009287c8 b elt.4095
009287cc b elt.4148
00926430 b errcount.6732
009263a4 b errcount.8155
00181670 d errname.6760
00928384 b error_statement_sym.4928
00928800 b exception_buffer
009287e0 b exception_status
00180a24 d f_first
00180a28 d f_fpe_top_of_stack
00926364 b f_fpe_traps
00180a2c d f_int_top_of_stack
00926368 b f_int_traps
001830e0 b f_mem_rec
001830c8 b f_memory_allocated
001830c4 b f_memory_length
001830c0 b f_memory_log_file
009242e0 b f_panic_callback_func
001830cc b f_peak_memory_usage
00180a30 d f_seg_top_of_stack
0092636c b f_seg_traps
00925300 b g_Asc_printVtables
00927acc b g_DeclarativeContext
00181320 d g_DefinitionErrorMessages
00927abc b g_EvaluationContext
00927ac0 b g_EvaluationForTable
00927ab8 b g_ExtVariablesTable
00927ab4 b g_ExternalFuncLibrary
00928018 b g_ExternalNodeStamps
00180e60 d g_abs_f
001812b0 D g_alt_ending
00926490 b g_ammarking
00180f20 d g_arccos_f
001810a0 d g_arccosh_f
00180ee0 d g_arcsin_f
00181060 d g_arcsinh_f
00180f60 d g_arctan_f
001810e0 d g_arctanh_f
00926494 b g_array_child_pool
00928444 b g_array_desc_count
00928448 b g_array_desc_list
0018309c b g_ascend_dllist
009264c0 b g_atom_bytes
009263b0 b g_atom_dim_ptr
0092bc50 b g_b_inst
0018187c d g_ba_elimdata
0092bc6c b g_ba_inst
0092863c b g_bad_rel_in_list
0092bc7c b g_bc_inst
00928434 b g_big_strings
00928438 b g_big_strings_cnt
00928640 b g_blockmethod
00180a60 d g_bt_data
00926398 b g_callargs
0092864c b g_case_number
00928030 b g_cbbccount
0092802c b g_cbbdcount
00181160 d g_cbrt_f
001812ec D g_check_dimensions_noisy
00926514 b g_clique_list
00181208 D g_compiler_counter
00928360 B g_compiler_timing
00180a34 D g_compiler_warnings
0092649c b g_cons
009263a0 b g_constant_type
009279d4 b g_copy_numnodes
00180d60 d g_cos_f
00180fe0 d g_cosh_f
00181120 d g_cube_f
00927f54 b g_current_module
0092bc48 b g_cursim
00926544 b g_def_child_bit_list
00926540 b g_def_child_desc_ptr
0092653c b g_def_child_list_ptr
009263b4 b g_default_dim_ptr
009263b8 b g_default_double
009263c0 b g_default_long
00928b4c b g_default_symbol
009263a8 b g_defaulted
00926534 b g_diagf
009263ac b g_dim_ptr
0092ac38 B g_dimen_list
0092ac30 b g_dimensionless
009286b4 b g_dis_tag
009284c0 b g_drt_depth
00927c28 b g_dummy_type
0092ac40 b g_dump_ht
0092bc40 b g_dump_inst_count
0092bc44 b g_dump_type_count
00926384 b g_end_identifier
001830a0 b g_env_list
00925340 b g_error_reporter_cache
00925328 b g_error_reporter_callback
00925320 b g_error_reporter_tree
00925324 b g_error_reporter_tree_current
00180c20 d g_exp_f
00927a50 b g_exprs_pool
00927c34 b g_externalmodel_type
009264fc b g_extra_parents
00926500 b g_extra_parents_sum
009264f8 b g_extra_paths
009288a0 b g_foreign_code_call_env
00927ad0 b g_forvar_recycle_list
00927ad4 b g_forvarfile
009289e0 B g_fpe_env
00927ad8 b g_free_store
001811a0 d g_func_list
00926370 b g_header_linenum
00180ea0 d g_hold_f
0092bc5c b g_i_inst
0092bc74 b g_ia_inst
0092bc60 b g_ic_inst
0017fce0 d g_instancetypenames
0018120c d g_instantiate_relns
00928a80 B g_int_env
001814f8 d g_iscomplete
0092844c b g_it_dummy_enum
00181310 d g_it_dummy_int
00927c00 b g_iteration
009284a8 b g_lcl_head
009284b8 b g_lcl_length
009284b4 b g_lcl_pivot
009284b0 b g_lcl_recycle
009284ac b g_lcl_tail
009284bc b g_lclrecycle_length
00181740 D g_linsolqr_timing
001818c0 b g_list_head_pool
00180c60 d g_ln_f
00180c08 D g_lnm_epsilon
00180ca0 d g_lnm_f
00180ce0 d g_log10_f
00927e40 b g_log_shortbuf
00927d54 b g_logrel_stack
00927c24 b g_logrel_type
00927f44 b g_logrelation_bvar_list
00927f48 b g_logrelation_satrel_list
00927f50 b g_logterm_pool
00181288 d g_logterm_ptrs
00927e34 b g_logwritfp
0092bc54 b g_lrel_inst
0092650c b g_maximum_children
009264f4 b g_maximum_parents
00926520 b g_maximum_relations
00926508 b g_minimum_children
009264f0 b g_minimum_parents
0092651c b g_minimum_relations
00926560 b g_missing
0092bc88 b g_mod_inst
009264b8 b g_model_bytes
00928000 b g_model_definition_methods
00926388 b g_model_parameters
00927f5c b g_module_list
00181220 d g_mpi_message
009287c4 b g_mtx_debug_redirect
0018185c d g_mtx_null_col_vector_data
0018181c d g_mtx_null_index_data
0018183c d g_mtx_null_mark_data
0018186c d g_mtx_null_row_vector_data
0018182c d g_mtx_null_sum_data
0018184c d g_mtx_null_vector_data
009301b4 b g_mtxerr
00927f6c b g_name_pool
009279e0 b g_names_needed
00927a58 b g_new_var_list
0092639c b g_notelist
00927f70 b g_notes_data_base
009264e8 b g_num_array_instances
009264dc b g_num_atom_children
009264bc b g_num_atom_instances
009264b0 b g_num_complex_instances
009264d8 b g_num_constant_all
009264cc b g_num_constant_bool
009264d0 b g_num_constant_int
009264c8 b g_num_constant_real
009264d4 b g_num_constant_sym
009264b4 b g_num_model_instances
00927f64 b g_num_names_cur
00927f68 b g_num_names_max
009264e0 b g_num_relation_instances
009264ec b g_num_unsel_instances
009284a4 b g_number
00927f90 b g_numlist_head_pool
00924300 b g_panic_outfile
00926390 b g_parameter_reduction
0092638c b g_parameter_wheres
0018130c d g_parse_count
00180a38 d g_parse_relns
009284c4 B g_parser_warnings
00927f9c b g_pending_count
00927fa0 b g_pending_list
00927fa4 b g_pending_list_end
00927fa8 b g_pending_pool
0092cca0 B g_plot_type
00927f94 b g_ppe_pool
001811fc d g_proc
00926378 b g_proc_name
00928004 b g_procframe_stop
00928008 b g_proto_count
0092ccc0 b g_proto_ht
0092bc94 b g_r_inst
0092bc78 b g_ra_inst
0092bc64 b g_rc_inst
00927a00 b g_recycle_expreval_stacks
00927f84 b g_recycled_npl
00926380 b g_refines_name
0092bc84 b g_rel_inst
00928040 b g_rel_stack
00928044 b g_rel_stack_pool
009264e4 b g_relation_guts
0092652c b g_relation_terms
00927c20 b g_relation_type
00928014 b g_relation_var_list
00928010 B g_relative_inst
00928618 b g_reuse
009286c4 b g_reuse
0092bc58 b g_s_inst
0092bc80 b g_sa_inst
0092bc90 b g_sc_inst
0092800c B g_search_inst
00928940 B g_seg_env
00928354 b g_set_pool
00927c30 b g_set_type
00928358 b g_sets_pool
00928220 b g_shortbuf
001812f4 d g_show_statement_detail
00927f4c b g_simplify_logrelations
001812cc D g_simplify_relations
0092835c B g_simulation_list
00180d20 d g_sin_f
00180fa0 d g_sinh_f
00927f60 b g_sldestroy
0092877c b g_solver_binary_type
009286c0 b g_solver_dis_type
00928778 b g_solver_int_type
00928780 b g_solver_semi_type
00928774 b g_solver_var_type
00180de0 d g_sqr_f
00180e20 d g_sqrt_f
00928414 b g_statio_flowtypenames
001812f8 d g_statio_label
009283a0 b g_statio_stattypenames
00928380 b g_statio_suppressions
00927b00 b g_string_buffer
00927f58 b g_string_modules_processed
00928428 b g_string_space
00927fc0 b g_strings
00928624 b g_strings
009286b8 b g_strings
009286d0 b g_strings
009286d4 b g_strings
00928758 b g_strings
00926498 b g_suppressions
0092bc8c b g_sym_inst
0092bc4c b g_syma_inst
00928430 b g_symbol_collisions
0092842c b g_symbol_size
0092dcc0 b g_symbol_table
00928614 b g_symbol_values_list
00927c40 b g_symbols
00928460 b g_symbols
009287ac b g_symbols
0092bc68 b g_symc_inst
00180da0 d g_tan_f
00181020 d g_tanh_f
0092843c b g_temporary_var_list
00928440 b g_temporary_var_recycle
0092801c b g_term_pool
001812d0 d g_term_ptrs
009284c8 b g_tlibs_depth
0092ab80 b g_token_counts
00926530 b g_total_array_children
00926510 b g_total_children
00926504 b g_total_parents
00926528 b g_total_reals_in_rels
00926524 b g_total_relations
00926518 b g_total_variables
009264c4 b g_tree_bytes
0092ac34 b g_trig_dimen
00927c04 b g_trychildexpansion_errmessage
009264ac b g_type_count_list
0092637c b g_type_name
00926394 b g_typeargs
00927c08 b g_unasscon_count
00928500 b g_unit_base_name
009284f0 b g_unit_explain_error_strings
00927adc b g_units_alloc
009284ec b g_units_collisions
001814c0 d g_units_errors.4640
0092f0e0 B g_units_hash_table
0092ecc0 b g_units_id_space
009263c4 b g_units_ptr
009284e8 b g_units_size
009284e0 b g_units_str
009284e4 b g_units_str_len
00927f98 b g_unresolved_count
00926374 b g_untrapped_error
00181204 D g_use_copyanon
0092852c b g_value_pool
00928754 b g_var_tag
0092bc70 b g_when_inst
00927c2c b g_when_type
0092ac3c b g_wild_dimen
0092642c b g_workbuf
00180a44 d g_workbuf_len.6555
00928214 b g_writfp
00928348 b glob_done
00927f40 b glob_lrel
00928340 b glob_rel
00928344 b glob_varnum
009279d0 b global_command_list
00928530 b global_visit_num
009287bc b hhrowlist.6528
00183074 b i.2578
00926354 b i.2755
00927ae0 b importhandler_library
00927ae4 b importhandler_sharedpointers
00926538 b init.5484
00928794 b init.6246
009287a0 b init.6716
0092878c b inst
009287c0 b last_value_matrix
00928798 b lastsolver.6445
00928330 b lhscap.9848
009287b8 b listlen.6529
00928784 b loaded.3887
00180ba0 d metadata.4158
001817e0 d mtxmagic
00928700 b name.6123
00928660 b name.6164
00181744 d names.4315
00181760 d names.4320
0018307c b newsize.2576
0092635c b newsize.2753
00181504 d nextid.6241
001812c8 d nostr.4857
00181688 d nrels.7185
0018168c d nrels.7199
009286fc b nuldev.5971
00181690 d nvars.7213
00183080 b oldsize.2575
00926360 b oldsize.2752
001817f2 d permmagic
00928648 b poly.3808
00928350 b poly.3924
00928644 b poly_cap.3809
0092834c b poly_cap.3925
00927a5c b previous_store.5962
0092833c b ptr.11160
009286dc b ptr.7376
00183078 b punt.2577
00926358 b punt.2754
00183098 b ref.2432
00928334 b rel.9847
009287a4 b reported_already.8633
009287a8 b reported_already.8653
00926580 b result.4159
009286e4 b rfilter.7742
0092832c b rhscap.9849
001817c0 d rsdata
001812f0 d safe_print_errors
0017fda0 d slv_reg
00928320 b soln_list.9691
00926418 b start_line
00928534 b stopnum.3912
00181508 d suppress_rel_flag.6780
00928788 b sys
001812a4 d unk.4785
00925304 b use_xterm_color.2533
009286ec b vfilter.7802
009286f4 b vfilter.7892
00928020 b warnexpt.5603
00928028 b warnexpt.5731
00928024 b warnfdiff.5732
009263f4 b yy_buffer_stack
009263f0 b yy_buffer_stack_max
009263ec b yy_buffer_stack_top
009263f8 b yy_c_buf_p
0092643c b yy_did_buffer_switch_on_eof
00926448 b yy_full_lp
00926440 b yy_full_match
0092644c b yy_full_state
00926434 b yy_hold_char
009263fc b yy_init
00180a40 d yy_line
0092640c b yy_looking_for_trail_begin
00926444 b yy_lp
00926410 b yy_more_offset
00926438 b yy_n_chars
00926414 b yy_prev_more_offset
00926400 b yy_start
00926404 b yy_state_buf
00926408 b yy_state_ptr
0092ab64 b yytext_ptr
009263e8 b zz__flex_debug
00928b50 b zz_char
009263e0 b zz_in
0092ab60 b zz_leng
00180a3c d zz_lineno
00928b20 b zz_lval
00928b54 b zz_nerrs
009263e4 b zz_out
00928b60 b zz_text
john@thunder:~/ascend$
</source>

== Static variables ==

Another place where quasi-global variables can occur is as static variables within functions. It needs to be assessed whether the above listing includes those types of variables.

Global variables

2012-07-06T18:29:41Z

BenAllan:

{{task}}

We would like to get rid of the current use of global variables in ASCEND, so that we can start to think about using ASCEND in multithreaded and/or embedded ways. This page will report any cases of global variables that we have found, and perhaps some discussion about how we can best eliminate them. Not all cases will be the same. Globals make some aspects of code reading easier (not crowding C arg lists with context pointers) and some harder: when complex side effects are in play. We try hard to avoid any usage of globals with complex side effects.

== Ways for removing global variables ==

A number of options exist:

* keeping them. This is appropriate in a very limited set of situations, such as for data that has been loaded from a configuration file when the program started.
* groupin them into a top-level data structure. We imagine structures like "library", "simulation" and "system" could be created that could hold most global variables.
* passing them. Where global variables have been used as a convenience to avoid having to expand function parameter lists, we can just change to passing them as parameters.
* converting them to #defines. May be appropriate for certain constants.
* converting them to thread-local variables (may need to assess implication for embedded applications)
* adding mutex constraints (so that they can only be accessed once at a time)
* migrating them to another code layer, eg into the GUI (this has already been done in some cases)

== Particular kinds of usage and what can be done about it ==

* Lex/Yacc C based scanners and parsers (and some still current versions of GNU bison/flex) generate code full of globals and non-threadsafe functions. It's not our job to fix this. The 'safe' thing to do is put a mutex around the parse function.
* ASCEND defined parser context flags, once properly identified, can remain global because the mutex for yacc will also protect them. Cosmetically, the 'properly identified' problem could be resolved by collecting these variables into a single well-named struct g_parser_context.
* Type library globals: most of these should be moved into a formal struct ascUniverse. More about that below.
* Instantiator tuning: most of these should be moved into a struct ascCompilerTuning.
* Memory recycle pools of small objects, tied to globals. These are tied to globals (typically file-scope static variables hidden behind allocator functions) to avoid passing pool pointers everywhere. In solvers like linsolqr, these pools should be tied to major objects instead of file global. "Too many pool objects, too short lived" is a problem that can be solved (taking mtx as an example, perhaps) by maintaining a list of idle mtx element pools; when to clear the idle pools is a minor problem. In the compiler, many pools should come and go with their Universe or with the destruction of the ascend type list and all dependent instances.

== The object lives in ascend, and a design for global use reduction ==
The most basic facts: ascend parses a set of type definitions into a self-consistent class hierarchy. These type definitions can then be used with the instantiator to create model instances with relation and variable data. These instance objects answer many queries by accessing pointers to the type definitions used to create the objects. ASCEND has a concept named UNIVERSAL (not unlike globals in C) whereby for a given type definition, only one instance will ever be constructed. Both types and instances are deeply tied to a symbol (constant strings) table. Throughout ascend, both types and symbols are heavily compared for identity by comparing pointers.

Key outcome of the above: if we wrap all the compiler globals in a context object of universal scope, we can then have at a higher (scripting) level multiple universe objects. *Objects from distinct universes cannot be compared except in string form*!

Given the above, then, ascend model type and instance data can be organized into something like the following. I will use c++ notation, but the implementation will be C.
<source>
class ascUniverse {
public:
// functions only
private:

};
</source>

== Global variables in libascend.so ==

The main place where global variables are a problem for ASCEND is in <tt>libascend</tt>, our core library include the ASCEND parser/compiler and evaluation routines, but '''hopefully''' excluding the solvers.

Below is a list of globals generated using GNU <tt>nm</tt>.

<source lang="sh">john@thunder:~/ascend$ nm libascend.so | grep -i " [DdGgSsBb] ";
001828a0 b AllowedContents
00926420 b BracesNestLevel
0092889c b CmpEv
0092641c b CommentNestLevel
00180be0 d DimNames
00927ac8 b EvaluatingSets
00926548 b FundamentalTypeList
00928528 b GlobalUniversalTable
00927c14 b InterfaceNotify
00927c0c b InterfacePtrATS
00927c10 b InterfacePtrDelete
00928790 b L.6247
0092879c b L.6717
0092bca0 b LibraryHashTable
00927ac4 b ListMode
00926424 b MatchedBackslash
00927a64 b MinusOne
00927a84 b One
001820c0 b RecycledContents
001818e0 b RecycledList
00926428 b RequireIndex
00926460 b RequireStack
009286e0 B Solv_C_CheckHalt_Flag
00927aa4 b Three
00927a94 b Two
001816a0 d VpTable
009300dc b X
00927a74 b Zero
0017fcc0 d __CTOR_END__
0017fcbc d __CTOR_LIST__
0017fcc8 d __DTOR_END__
0017fcc4 d __DTOR_LIST__
0017fccc d __JCR_END__
0017fccc d __JCR_LIST__
00180a20 d __dso_handle
00181811 d blockend
001817fc d blockmagic
001814fc D calc_ok
00181500 d calc_print_errors
00928338 b cap.11161
009286d8 b cap.7377
00181520 d commands
001818a0 b completed.6625
009300e0 b conopt_fptrs
00927a54 b constants_inited
001817d0 d csdata
00183088 b dcps.2434
00926488 b default_library_path.7912
0092648c b default_solvers_path.7911
0018167c d defaultintegrators.6720
00927a60 b deriv_store.5961
00926564 b done.4160
00183090 b dref.2433
00927c80 b ds.3670
00927d60 b ds.4078
00928540 b ds.4252
00928060 b ds.4837
00928140 b ds.5578
001818a4 b dtor_idx.6627
009287c8 b elt.4095
009287cc b elt.4148
00926430 b errcount.6732
009263a4 b errcount.8155
00181670 d errname.6760
00928384 b error_statement_sym.4928
00928800 b exception_buffer
009287e0 b exception_status
00180a24 d f_first
00180a28 d f_fpe_top_of_stack
00926364 b f_fpe_traps
00180a2c d f_int_top_of_stack
00926368 b f_int_traps
001830e0 b f_mem_rec
001830c8 b f_memory_allocated
001830c4 b f_memory_length
001830c0 b f_memory_log_file
009242e0 b f_panic_callback_func
001830cc b f_peak_memory_usage
00180a30 d f_seg_top_of_stack
0092636c b f_seg_traps
00925300 b g_Asc_printVtables
00927acc b g_DeclarativeContext
00181320 d g_DefinitionErrorMessages
00927abc b g_EvaluationContext
00927ac0 b g_EvaluationForTable
00927ab8 b g_ExtVariablesTable
00927ab4 b g_ExternalFuncLibrary
00928018 b g_ExternalNodeStamps
00180e60 d g_abs_f
001812b0 D g_alt_ending
00926490 b g_ammarking
00180f20 d g_arccos_f
001810a0 d g_arccosh_f
00180ee0 d g_arcsin_f
00181060 d g_arcsinh_f
00180f60 d g_arctan_f
001810e0 d g_arctanh_f
00926494 b g_array_child_pool
00928444 b g_array_desc_count
00928448 b g_array_desc_list
0018309c b g_ascend_dllist
009264c0 b g_atom_bytes
009263b0 b g_atom_dim_ptr
0092bc50 b g_b_inst
0018187c d g_ba_elimdata
0092bc6c b g_ba_inst
0092863c b g_bad_rel_in_list
0092bc7c b g_bc_inst
00928434 b g_big_strings
00928438 b g_big_strings_cnt
00928640 b g_blockmethod
00180a60 d g_bt_data
00926398 b g_callargs
0092864c b g_case_number
00928030 b g_cbbccount
0092802c b g_cbbdcount
00181160 d g_cbrt_f
001812ec D g_check_dimensions_noisy
00926514 b g_clique_list
00181208 D g_compiler_counter
00928360 B g_compiler_timing
00180a34 D g_compiler_warnings
0092649c b g_cons
009263a0 b g_constant_type
009279d4 b g_copy_numnodes
00180d60 d g_cos_f
00180fe0 d g_cosh_f
00181120 d g_cube_f
00927f54 b g_current_module
0092bc48 b g_cursim
00926544 b g_def_child_bit_list
00926540 b g_def_child_desc_ptr
0092653c b g_def_child_list_ptr
009263b4 b g_default_dim_ptr
009263b8 b g_default_double
009263c0 b g_default_long
00928b4c b g_default_symbol
009263a8 b g_defaulted
00926534 b g_diagf
009263ac b g_dim_ptr
0092ac38 B g_dimen_list
0092ac30 b g_dimensionless
009286b4 b g_dis_tag
009284c0 b g_drt_depth
00927c28 b g_dummy_type
0092ac40 b g_dump_ht
0092bc40 b g_dump_inst_count
0092bc44 b g_dump_type_count
00926384 b g_end_identifier
001830a0 b g_env_list
00925340 b g_error_reporter_cache
00925328 b g_error_reporter_callback
00925320 b g_error_reporter_tree
00925324 b g_error_reporter_tree_current
00180c20 d g_exp_f
00927a50 b g_exprs_pool
00927c34 b g_externalmodel_type
009264fc b g_extra_parents
00926500 b g_extra_parents_sum
009264f8 b g_extra_paths
009288a0 b g_foreign_code_call_env
00927ad0 b g_forvar_recycle_list
00927ad4 b g_forvarfile
009289e0 B g_fpe_env
00927ad8 b g_free_store
001811a0 d g_func_list
00926370 b g_header_linenum
00180ea0 d g_hold_f
0092bc5c b g_i_inst
0092bc74 b g_ia_inst
0092bc60 b g_ic_inst
0017fce0 d g_instancetypenames
0018120c d g_instantiate_relns
00928a80 B g_int_env
001814f8 d g_iscomplete
0092844c b g_it_dummy_enum
00181310 d g_it_dummy_int
00927c00 b g_iteration
009284a8 b g_lcl_head
009284b8 b g_lcl_length
009284b4 b g_lcl_pivot
009284b0 b g_lcl_recycle
009284ac b g_lcl_tail
009284bc b g_lclrecycle_length
00181740 D g_linsolqr_timing
001818c0 b g_list_head_pool
00180c60 d g_ln_f
00180c08 D g_lnm_epsilon
00180ca0 d g_lnm_f
00180ce0 d g_log10_f
00927e40 b g_log_shortbuf
00927d54 b g_logrel_stack
00927c24 b g_logrel_type
00927f44 b g_logrelation_bvar_list
00927f48 b g_logrelation_satrel_list
00927f50 b g_logterm_pool
00181288 d g_logterm_ptrs
00927e34 b g_logwritfp
0092bc54 b g_lrel_inst
0092650c b g_maximum_children
009264f4 b g_maximum_parents
00926520 b g_maximum_relations
00926508 b g_minimum_children
009264f0 b g_minimum_parents
0092651c b g_minimum_relations
00926560 b g_missing
0092bc88 b g_mod_inst
009264b8 b g_model_bytes
00928000 b g_model_definition_methods
00926388 b g_model_parameters
00927f5c b g_module_list
00181220 d g_mpi_message
009287c4 b g_mtx_debug_redirect
0018185c d g_mtx_null_col_vector_data
0018181c d g_mtx_null_index_data
0018183c d g_mtx_null_mark_data
0018186c d g_mtx_null_row_vector_data
0018182c d g_mtx_null_sum_data
0018184c d g_mtx_null_vector_data
009301b4 b g_mtxerr
00927f6c b g_name_pool
009279e0 b g_names_needed
00927a58 b g_new_var_list
0092639c b g_notelist
00927f70 b g_notes_data_base
009264e8 b g_num_array_instances
009264dc b g_num_atom_children
009264bc b g_num_atom_instances
009264b0 b g_num_complex_instances
009264d8 b g_num_constant_all
009264cc b g_num_constant_bool
009264d0 b g_num_constant_int
009264c8 b g_num_constant_real
009264d4 b g_num_constant_sym
009264b4 b g_num_model_instances
00927f64 b g_num_names_cur
00927f68 b g_num_names_max
009264e0 b g_num_relation_instances
009264ec b g_num_unsel_instances
009284a4 b g_number
00927f90 b g_numlist_head_pool
00924300 b g_panic_outfile
00926390 b g_parameter_reduction
0092638c b g_parameter_wheres
0018130c d g_parse_count
00180a38 d g_parse_relns
009284c4 B g_parser_warnings
00927f9c b g_pending_count
00927fa0 b g_pending_list
00927fa4 b g_pending_list_end
00927fa8 b g_pending_pool
0092cca0 B g_plot_type
00927f94 b g_ppe_pool
001811fc d g_proc
00926378 b g_proc_name
00928004 b g_procframe_stop
00928008 b g_proto_count
0092ccc0 b g_proto_ht
0092bc94 b g_r_inst
0092bc78 b g_ra_inst
0092bc64 b g_rc_inst
00927a00 b g_recycle_expreval_stacks
00927f84 b g_recycled_npl
00926380 b g_refines_name
0092bc84 b g_rel_inst
00928040 b g_rel_stack
00928044 b g_rel_stack_pool
009264e4 b g_relation_guts
0092652c b g_relation_terms
00927c20 b g_relation_type
00928014 b g_relation_var_list
00928010 B g_relative_inst
00928618 b g_reuse
009286c4 b g_reuse
0092bc58 b g_s_inst
0092bc80 b g_sa_inst
0092bc90 b g_sc_inst
0092800c B g_search_inst
00928940 B g_seg_env
00928354 b g_set_pool
00927c30 b g_set_type
00928358 b g_sets_pool
00928220 b g_shortbuf
001812f4 d g_show_statement_detail
00927f4c b g_simplify_logrelations
001812cc D g_simplify_relations
0092835c B g_simulation_list
00180d20 d g_sin_f
00180fa0 d g_sinh_f
00927f60 b g_sldestroy
0092877c b g_solver_binary_type
009286c0 b g_solver_dis_type
00928778 b g_solver_int_type
00928780 b g_solver_semi_type
00928774 b g_solver_var_type
00180de0 d g_sqr_f
00180e20 d g_sqrt_f
00928414 b g_statio_flowtypenames
001812f8 d g_statio_label
009283a0 b g_statio_stattypenames
00928380 b g_statio_suppressions
00927b00 b g_string_buffer
00927f58 b g_string_modules_processed
00928428 b g_string_space
00927fc0 b g_strings
00928624 b g_strings
009286b8 b g_strings
009286d0 b g_strings
009286d4 b g_strings
00928758 b g_strings
00926498 b g_suppressions
0092bc8c b g_sym_inst
0092bc4c b g_syma_inst
00928430 b g_symbol_collisions
0092842c b g_symbol_size
0092dcc0 b g_symbol_table
00928614 b g_symbol_values_list
00927c40 b g_symbols
00928460 b g_symbols
009287ac b g_symbols
0092bc68 b g_symc_inst
00180da0 d g_tan_f
00181020 d g_tanh_f
0092843c b g_temporary_var_list
00928440 b g_temporary_var_recycle
0092801c b g_term_pool
001812d0 d g_term_ptrs
009284c8 b g_tlibs_depth
0092ab80 b g_token_counts
00926530 b g_total_array_children
00926510 b g_total_children
00926504 b g_total_parents
00926528 b g_total_reals_in_rels
00926524 b g_total_relations
00926518 b g_total_variables
009264c4 b g_tree_bytes
0092ac34 b g_trig_dimen
00927c04 b g_trychildexpansion_errmessage
009264ac b g_type_count_list
0092637c b g_type_name
00926394 b g_typeargs
00927c08 b g_unasscon_count
00928500 b g_unit_base_name
009284f0 b g_unit_explain_error_strings
00927adc b g_units_alloc
009284ec b g_units_collisions
001814c0 d g_units_errors.4640
0092f0e0 B g_units_hash_table
0092ecc0 b g_units_id_space
009263c4 b g_units_ptr
009284e8 b g_units_size
009284e0 b g_units_str
009284e4 b g_units_str_len
00927f98 b g_unresolved_count
00926374 b g_untrapped_error
00181204 D g_use_copyanon
0092852c b g_value_pool
00928754 b g_var_tag
0092bc70 b g_when_inst
00927c2c b g_when_type
0092ac3c b g_wild_dimen
0092642c b g_workbuf
00180a44 d g_workbuf_len.6555
00928214 b g_writfp
00928348 b glob_done
00927f40 b glob_lrel
00928340 b glob_rel
00928344 b glob_varnum
009279d0 b global_command_list
00928530 b global_visit_num
009287bc b hhrowlist.6528
00183074 b i.2578
00926354 b i.2755
00927ae0 b importhandler_library
00927ae4 b importhandler_sharedpointers
00926538 b init.5484
00928794 b init.6246
009287a0 b init.6716
0092878c b inst
009287c0 b last_value_matrix
00928798 b lastsolver.6445
00928330 b lhscap.9848
009287b8 b listlen.6529
00928784 b loaded.3887
00180ba0 d metadata.4158
001817e0 d mtxmagic
00928700 b name.6123
00928660 b name.6164
00181744 d names.4315
00181760 d names.4320
0018307c b newsize.2576
0092635c b newsize.2753
00181504 d nextid.6241
001812c8 d nostr.4857
00181688 d nrels.7185
0018168c d nrels.7199
009286fc b nuldev.5971
00181690 d nvars.7213
00183080 b oldsize.2575
00926360 b oldsize.2752
001817f2 d permmagic
00928648 b poly.3808
00928350 b poly.3924
00928644 b poly_cap.3809
0092834c b poly_cap.3925
00927a5c b previous_store.5962
0092833c b ptr.11160
009286dc b ptr.7376
00183078 b punt.2577
00926358 b punt.2754
00183098 b ref.2432
00928334 b rel.9847
009287a4 b reported_already.8633
009287a8 b reported_already.8653
00926580 b result.4159
009286e4 b rfilter.7742
0092832c b rhscap.9849
001817c0 d rsdata
001812f0 d safe_print_errors
0017fda0 d slv_reg
00928320 b soln_list.9691
00926418 b start_line
00928534 b stopnum.3912
00181508 d suppress_rel_flag.6780
00928788 b sys
001812a4 d unk.4785
00925304 b use_xterm_color.2533
009286ec b vfilter.7802
009286f4 b vfilter.7892
00928020 b warnexpt.5603
00928028 b warnexpt.5731
00928024 b warnfdiff.5732
009263f4 b yy_buffer_stack
009263f0 b yy_buffer_stack_max
009263ec b yy_buffer_stack_top
009263f8 b yy_c_buf_p
0092643c b yy_did_buffer_switch_on_eof
00926448 b yy_full_lp
00926440 b yy_full_match
0092644c b yy_full_state
00926434 b yy_hold_char
009263fc b yy_init
00180a40 d yy_line
0092640c b yy_looking_for_trail_begin
00926444 b yy_lp
00926410 b yy_more_offset
00926438 b yy_n_chars
00926414 b yy_prev_more_offset
00926400 b yy_start
00926404 b yy_state_buf
00926408 b yy_state_ptr
0092ab64 b yytext_ptr
009263e8 b zz__flex_debug
00928b50 b zz_char
009263e0 b zz_in
0092ab60 b zz_leng
00180a3c d zz_lineno
00928b20 b zz_lval
00928b54 b zz_nerrs
009263e4 b zz_out
00928b60 b zz_text
john@thunder:~/ascend$
</source>

== Static variables ==

Another place where quasi-global variables can occur is as static variables within functions. It needs to be assessed whether the above listing includes those types of variables.

Global variables

2012-07-06T18:14:11Z

BenAllan:

{{task}}

We would like to get rid of the current use of global variables in ASCEND, so that we can start to think about using ASCEND in multithreaded and/or embedded ways. This page will report any cases of global variables that we have found, and perhaps some discussion about how we can best eliminate them. Not all cases will be the same. Globals make some aspects of code reading easier (not crowding C arg lists with context pointers) and some harder: when complex side effects are in play. We try hard to avoid any usage of globals with complex side effects.

== Ways for removing global variables ==

A number of options exist:

* keeping them. This is appropriate in a very limited set of situations, such as for data that has been loaded from a configuration file when the program started.
* groupin them into a top-level data structure. We imagine structures like "library", "simulation" and "system" could be created that could hold most global variables.
* passing them. Where global variables have been used as a convenience to avoid having to expand function parameter lists, we can just change to passing them as parameters.
* converting them to #defines. May be appropriate for certain constants.
* converting them to thread-local variables (may need to assess implication for embedded applications)
* adding mutex constraints (so that they can only be accessed once at a time)
* migrating them to another code layer, eg into the GUI (this has already been done in some cases)

== Particular kinds of usage and what can be done about it ==

* Lex/Yacc C based scanners and parsers (and some still current versions of GNU bison/flex) generate code full of globals and non-threadsafe functions. It's not our job to fix this. The 'safe' thing to do is put a mutex around the parse function.
* ASCEND defined parser context flags, once properly identified, can remain global because the mutex for yacc will also protect them. Cosmetically, the 'properly identified' problem could be resolved by collecting these variables into a single well-named struct g_parser_context.
* Type library globals: most of these should be moved into a formal struct ascUniverse. More about that below.
* Instantiator tuning: most of these should be moved into a struct ascCompilerTuning.
* Memory recycle pools of small objects, tied to globals. These are tied to globals (typically file-scope static variables hidden behind allocator functions) to avoid passing pool pointers everywhere. In solvers like linsolqr, these pools should be tied to major objects instead of file global. "Too many pool objects, too short lived" is a problem that can be solved (taking mtx as an example, perhaps) by maintaining a list of idle mtx element pools; when to clear the idle pools is a minor problem. In the compiler, many pools should come and go with their Universe or with the destruction of the ascend type list and all dependent instances.

== Global variables in libascend.so ==

The main place where global variables are a problem for ASCEND is in <tt>libascend</tt>, our core library include the ASCEND parser/compiler and evaluation routines, but '''hopefully''' excluding the solvers.

Below is a list of globals generated using GNU <tt>nm</tt>.

<source lang="sh">john@thunder:~/ascend$ nm libascend.so | grep -i " [DdGgSsBb] ";
001828a0 b AllowedContents
00926420 b BracesNestLevel
0092889c b CmpEv
0092641c b CommentNestLevel
00180be0 d DimNames
00927ac8 b EvaluatingSets
00926548 b FundamentalTypeList
00928528 b GlobalUniversalTable
00927c14 b InterfaceNotify
00927c0c b InterfacePtrATS
00927c10 b InterfacePtrDelete
00928790 b L.6247
0092879c b L.6717
0092bca0 b LibraryHashTable
00927ac4 b ListMode
00926424 b MatchedBackslash
00927a64 b MinusOne
00927a84 b One
001820c0 b RecycledContents
001818e0 b RecycledList
00926428 b RequireIndex
00926460 b RequireStack
009286e0 B Solv_C_CheckHalt_Flag
00927aa4 b Three
00927a94 b Two
001816a0 d VpTable
009300dc b X
00927a74 b Zero
0017fcc0 d __CTOR_END__
0017fcbc d __CTOR_LIST__
0017fcc8 d __DTOR_END__
0017fcc4 d __DTOR_LIST__
0017fccc d __JCR_END__
0017fccc d __JCR_LIST__
00180a20 d __dso_handle
00181811 d blockend
001817fc d blockmagic
001814fc D calc_ok
00181500 d calc_print_errors
00928338 b cap.11161
009286d8 b cap.7377
00181520 d commands
001818a0 b completed.6625
009300e0 b conopt_fptrs
00927a54 b constants_inited
001817d0 d csdata
00183088 b dcps.2434
00926488 b default_library_path.7912
0092648c b default_solvers_path.7911
0018167c d defaultintegrators.6720
00927a60 b deriv_store.5961
00926564 b done.4160
00183090 b dref.2433
00927c80 b ds.3670
00927d60 b ds.4078
00928540 b ds.4252
00928060 b ds.4837
00928140 b ds.5578
001818a4 b dtor_idx.6627
009287c8 b elt.4095
009287cc b elt.4148
00926430 b errcount.6732
009263a4 b errcount.8155
00181670 d errname.6760
00928384 b error_statement_sym.4928
00928800 b exception_buffer
009287e0 b exception_status
00180a24 d f_first
00180a28 d f_fpe_top_of_stack
00926364 b f_fpe_traps
00180a2c d f_int_top_of_stack
00926368 b f_int_traps
001830e0 b f_mem_rec
001830c8 b f_memory_allocated
001830c4 b f_memory_length
001830c0 b f_memory_log_file
009242e0 b f_panic_callback_func
001830cc b f_peak_memory_usage
00180a30 d f_seg_top_of_stack
0092636c b f_seg_traps
00925300 b g_Asc_printVtables
00927acc b g_DeclarativeContext
00181320 d g_DefinitionErrorMessages
00927abc b g_EvaluationContext
00927ac0 b g_EvaluationForTable
00927ab8 b g_ExtVariablesTable
00927ab4 b g_ExternalFuncLibrary
00928018 b g_ExternalNodeStamps
00180e60 d g_abs_f
001812b0 D g_alt_ending
00926490 b g_ammarking
00180f20 d g_arccos_f
001810a0 d g_arccosh_f
00180ee0 d g_arcsin_f
00181060 d g_arcsinh_f
00180f60 d g_arctan_f
001810e0 d g_arctanh_f
00926494 b g_array_child_pool
00928444 b g_array_desc_count
00928448 b g_array_desc_list
0018309c b g_ascend_dllist
009264c0 b g_atom_bytes
009263b0 b g_atom_dim_ptr
0092bc50 b g_b_inst
0018187c d g_ba_elimdata
0092bc6c b g_ba_inst
0092863c b g_bad_rel_in_list
0092bc7c b g_bc_inst
00928434 b g_big_strings
00928438 b g_big_strings_cnt
00928640 b g_blockmethod
00180a60 d g_bt_data
00926398 b g_callargs
0092864c b g_case_number
00928030 b g_cbbccount
0092802c b g_cbbdcount
00181160 d g_cbrt_f
001812ec D g_check_dimensions_noisy
00926514 b g_clique_list
00181208 D g_compiler_counter
00928360 B g_compiler_timing
00180a34 D g_compiler_warnings
0092649c b g_cons
009263a0 b g_constant_type
009279d4 b g_copy_numnodes
00180d60 d g_cos_f
00180fe0 d g_cosh_f
00181120 d g_cube_f
00927f54 b g_current_module
0092bc48 b g_cursim
00926544 b g_def_child_bit_list
00926540 b g_def_child_desc_ptr
0092653c b g_def_child_list_ptr
009263b4 b g_default_dim_ptr
009263b8 b g_default_double
009263c0 b g_default_long
00928b4c b g_default_symbol
009263a8 b g_defaulted
00926534 b g_diagf
009263ac b g_dim_ptr
0092ac38 B g_dimen_list
0092ac30 b g_dimensionless
009286b4 b g_dis_tag
009284c0 b g_drt_depth
00927c28 b g_dummy_type
0092ac40 b g_dump_ht
0092bc40 b g_dump_inst_count
0092bc44 b g_dump_type_count
00926384 b g_end_identifier
001830a0 b g_env_list
00925340 b g_error_reporter_cache
00925328 b g_error_reporter_callback
00925320 b g_error_reporter_tree
00925324 b g_error_reporter_tree_current
00180c20 d g_exp_f
00927a50 b g_exprs_pool
00927c34 b g_externalmodel_type
009264fc b g_extra_parents
00926500 b g_extra_parents_sum
009264f8 b g_extra_paths
009288a0 b g_foreign_code_call_env
00927ad0 b g_forvar_recycle_list
00927ad4 b g_forvarfile
009289e0 B g_fpe_env
00927ad8 b g_free_store
001811a0 d g_func_list
00926370 b g_header_linenum
00180ea0 d g_hold_f
0092bc5c b g_i_inst
0092bc74 b g_ia_inst
0092bc60 b g_ic_inst
0017fce0 d g_instancetypenames
0018120c d g_instantiate_relns
00928a80 B g_int_env
001814f8 d g_iscomplete
0092844c b g_it_dummy_enum
00181310 d g_it_dummy_int
00927c00 b g_iteration
009284a8 b g_lcl_head
009284b8 b g_lcl_length
009284b4 b g_lcl_pivot
009284b0 b g_lcl_recycle
009284ac b g_lcl_tail
009284bc b g_lclrecycle_length
00181740 D g_linsolqr_timing
001818c0 b g_list_head_pool
00180c60 d g_ln_f
00180c08 D g_lnm_epsilon
00180ca0 d g_lnm_f
00180ce0 d g_log10_f
00927e40 b g_log_shortbuf
00927d54 b g_logrel_stack
00927c24 b g_logrel_type
00927f44 b g_logrelation_bvar_list
00927f48 b g_logrelation_satrel_list
00927f50 b g_logterm_pool
00181288 d g_logterm_ptrs
00927e34 b g_logwritfp
0092bc54 b g_lrel_inst
0092650c b g_maximum_children
009264f4 b g_maximum_parents
00926520 b g_maximum_relations
00926508 b g_minimum_children
009264f0 b g_minimum_parents
0092651c b g_minimum_relations
00926560 b g_missing
0092bc88 b g_mod_inst
009264b8 b g_model_bytes
00928000 b g_model_definition_methods
00926388 b g_model_parameters
00927f5c b g_module_list
00181220 d g_mpi_message
009287c4 b g_mtx_debug_redirect
0018185c d g_mtx_null_col_vector_data
0018181c d g_mtx_null_index_data
0018183c d g_mtx_null_mark_data
0018186c d g_mtx_null_row_vector_data
0018182c d g_mtx_null_sum_data
0018184c d g_mtx_null_vector_data
009301b4 b g_mtxerr
00927f6c b g_name_pool
009279e0 b g_names_needed
00927a58 b g_new_var_list
0092639c b g_notelist
00927f70 b g_notes_data_base
009264e8 b g_num_array_instances
009264dc b g_num_atom_children
009264bc b g_num_atom_instances
009264b0 b g_num_complex_instances
009264d8 b g_num_constant_all
009264cc b g_num_constant_bool
009264d0 b g_num_constant_int
009264c8 b g_num_constant_real
009264d4 b g_num_constant_sym
009264b4 b g_num_model_instances
00927f64 b g_num_names_cur
00927f68 b g_num_names_max
009264e0 b g_num_relation_instances
009264ec b g_num_unsel_instances
009284a4 b g_number
00927f90 b g_numlist_head_pool
00924300 b g_panic_outfile
00926390 b g_parameter_reduction
0092638c b g_parameter_wheres
0018130c d g_parse_count
00180a38 d g_parse_relns
009284c4 B g_parser_warnings
00927f9c b g_pending_count
00927fa0 b g_pending_list
00927fa4 b g_pending_list_end
00927fa8 b g_pending_pool
0092cca0 B g_plot_type
00927f94 b g_ppe_pool
001811fc d g_proc
00926378 b g_proc_name
00928004 b g_procframe_stop
00928008 b g_proto_count
0092ccc0 b g_proto_ht
0092bc94 b g_r_inst
0092bc78 b g_ra_inst
0092bc64 b g_rc_inst
00927a00 b g_recycle_expreval_stacks
00927f84 b g_recycled_npl
00926380 b g_refines_name
0092bc84 b g_rel_inst
00928040 b g_rel_stack
00928044 b g_rel_stack_pool
009264e4 b g_relation_guts
0092652c b g_relation_terms
00927c20 b g_relation_type
00928014 b g_relation_var_list
00928010 B g_relative_inst
00928618 b g_reuse
009286c4 b g_reuse
0092bc58 b g_s_inst
0092bc80 b g_sa_inst
0092bc90 b g_sc_inst
0092800c B g_search_inst
00928940 B g_seg_env
00928354 b g_set_pool
00927c30 b g_set_type
00928358 b g_sets_pool
00928220 b g_shortbuf
001812f4 d g_show_statement_detail
00927f4c b g_simplify_logrelations
001812cc D g_simplify_relations
0092835c B g_simulation_list
00180d20 d g_sin_f
00180fa0 d g_sinh_f
00927f60 b g_sldestroy
0092877c b g_solver_binary_type
009286c0 b g_solver_dis_type
00928778 b g_solver_int_type
00928780 b g_solver_semi_type
00928774 b g_solver_var_type
00180de0 d g_sqr_f
00180e20 d g_sqrt_f
00928414 b g_statio_flowtypenames
001812f8 d g_statio_label
009283a0 b g_statio_stattypenames
00928380 b g_statio_suppressions
00927b00 b g_string_buffer
00927f58 b g_string_modules_processed
00928428 b g_string_space
00927fc0 b g_strings
00928624 b g_strings
009286b8 b g_strings
009286d0 b g_strings
009286d4 b g_strings
00928758 b g_strings
00926498 b g_suppressions
0092bc8c b g_sym_inst
0092bc4c b g_syma_inst
00928430 b g_symbol_collisions
0092842c b g_symbol_size
0092dcc0 b g_symbol_table
00928614 b g_symbol_values_list
00927c40 b g_symbols
00928460 b g_symbols
009287ac b g_symbols
0092bc68 b g_symc_inst
00180da0 d g_tan_f
00181020 d g_tanh_f
0092843c b g_temporary_var_list
00928440 b g_temporary_var_recycle
0092801c b g_term_pool
001812d0 d g_term_ptrs
009284c8 b g_tlibs_depth
0092ab80 b g_token_counts
00926530 b g_total_array_children
00926510 b g_total_children
00926504 b g_total_parents
00926528 b g_total_reals_in_rels
00926524 b g_total_relations
00926518 b g_total_variables
009264c4 b g_tree_bytes
0092ac34 b g_trig_dimen
00927c04 b g_trychildexpansion_errmessage
009264ac b g_type_count_list
0092637c b g_type_name
00926394 b g_typeargs
00927c08 b g_unasscon_count
00928500 b g_unit_base_name
009284f0 b g_unit_explain_error_strings
00927adc b g_units_alloc
009284ec b g_units_collisions
001814c0 d g_units_errors.4640
0092f0e0 B g_units_hash_table
0092ecc0 b g_units_id_space
009263c4 b g_units_ptr
009284e8 b g_units_size
009284e0 b g_units_str
009284e4 b g_units_str_len
00927f98 b g_unresolved_count
00926374 b g_untrapped_error
00181204 D g_use_copyanon
0092852c b g_value_pool
00928754 b g_var_tag
0092bc70 b g_when_inst
00927c2c b g_when_type
0092ac3c b g_wild_dimen
0092642c b g_workbuf
00180a44 d g_workbuf_len.6555
00928214 b g_writfp
00928348 b glob_done
00927f40 b glob_lrel
00928340 b glob_rel
00928344 b glob_varnum
009279d0 b global_command_list
00928530 b global_visit_num
009287bc b hhrowlist.6528
00183074 b i.2578
00926354 b i.2755
00927ae0 b importhandler_library
00927ae4 b importhandler_sharedpointers
00926538 b init.5484
00928794 b init.6246
009287a0 b init.6716
0092878c b inst
009287c0 b last_value_matrix
00928798 b lastsolver.6445
00928330 b lhscap.9848
009287b8 b listlen.6529
00928784 b loaded.3887
00180ba0 d metadata.4158
001817e0 d mtxmagic
00928700 b name.6123
00928660 b name.6164
00181744 d names.4315
00181760 d names.4320
0018307c b newsize.2576
0092635c b newsize.2753
00181504 d nextid.6241
001812c8 d nostr.4857
00181688 d nrels.7185
0018168c d nrels.7199
009286fc b nuldev.5971
00181690 d nvars.7213
00183080 b oldsize.2575
00926360 b oldsize.2752
001817f2 d permmagic
00928648 b poly.3808
00928350 b poly.3924
00928644 b poly_cap.3809
0092834c b poly_cap.3925
00927a5c b previous_store.5962
0092833c b ptr.11160
009286dc b ptr.7376
00183078 b punt.2577
00926358 b punt.2754
00183098 b ref.2432
00928334 b rel.9847
009287a4 b reported_already.8633
009287a8 b reported_already.8653
00926580 b result.4159
009286e4 b rfilter.7742
0092832c b rhscap.9849
001817c0 d rsdata
001812f0 d safe_print_errors
0017fda0 d slv_reg
00928320 b soln_list.9691
00926418 b start_line
00928534 b stopnum.3912
00181508 d suppress_rel_flag.6780
00928788 b sys
001812a4 d unk.4785
00925304 b use_xterm_color.2533
009286ec b vfilter.7802
009286f4 b vfilter.7892
00928020 b warnexpt.5603
00928028 b warnexpt.5731
00928024 b warnfdiff.5732
009263f4 b yy_buffer_stack
009263f0 b yy_buffer_stack_max
009263ec b yy_buffer_stack_top
009263f8 b yy_c_buf_p
0092643c b yy_did_buffer_switch_on_eof
00926448 b yy_full_lp
00926440 b yy_full_match
0092644c b yy_full_state
00926434 b yy_hold_char
009263fc b yy_init
00180a40 d yy_line
0092640c b yy_looking_for_trail_begin
00926444 b yy_lp
00926410 b yy_more_offset
00926438 b yy_n_chars
00926414 b yy_prev_more_offset
00926400 b yy_start
00926404 b yy_state_buf
00926408 b yy_state_ptr
0092ab64 b yytext_ptr
009263e8 b zz__flex_debug
00928b50 b zz_char
009263e0 b zz_in
0092ab60 b zz_leng
00180a3c d zz_lineno
00928b20 b zz_lval
00928b54 b zz_nerrs
009263e4 b zz_out
00928b60 b zz_text
john@thunder:~/ascend$
</source>

== Static variables ==

Another place where quasi-global variables can occur is as static variables within functions. It needs to be assessed whether the above listing includes those types of variables.

Building ASCEND

2012-03-11T21:30:17Z

BenAllan: /* Ubuntu 11.10 */

This page contains specific instructions for building ASCEND on systems that we know about. First you should read about [[VersionManagement]] for information on how to get hold of the source code.

Building ASCEND (as of March 2006) requires the [http://www.scons.org/ SCons] build tool. In our opinion, SCons is a significant advance on Autotools, so we encourage you to give it a chance, if you're not familiar with it. If you are interested in the implementation details of our build scripts, please see our [[developer's manual]].

'''Note:''' If you are having trouble building ASCEND, it might be worth checking out the [[BuildBot]] (link [http://ascend.cheme.cmu.edu:8011/ here]) to see if the latest sources have compiled correctly on our test server.

== General instructions ==

Building with SCons (as of Jun 2010, we recommend version 1.x) should be as simple as typing

<source lang="a4c">scons</source>

Get info on the [[SCons_options_for_building_ASCEND|current build options]] by typing <tt>scons -Qh</tt>. To clean up after your build, type <tt>scons -c</tt>. To include any building options, type <tt>scons</tt> followed by options. For instance, type <tt>scons WITH_LOCAL_HELP = /usr/local/share/ascend/manual</tt>.

Any build option that you see in <tt>scons -Qh</tt> can be entered into a file <tt>config.py</tt> that you can create in the root source directory (ie <tt>~/src/ascend/trunk</tt>). For example, you might create a config.py file like this:

<pre>WITH_LOCAL_HELP = /usr/local/share/ascend/manual
DEFAULT_ASCENDLIBRARY = /usr/local/share/ascend/models
</pre>

So, if you want to set configuration options so that they always get applied, edit your <tt>config.py</tt> file.

On top of that, you should also be aware that the SCons build will cache your build options in a file called <tt>options.cache</tt>. That means that if you type a scons command with command-line options, then later without those command line options, the options from the first run will still be there, because they will have been saved in the cache.

A major fiddle with SCons, especially on Windows, is ensuring that all the required programs are present in your path. You need to install Bison (from the GnuWin32 project). For SCons to run correctly from the MSYS command line, you will also need to add <tt>/c/Python25/Scripts:/c/Python25</tt> to your path, so that the 'scons' script is discovered.

The SCons system will manage the building of FORTRAN components and is able to link to an installed version of CONOPT.

For instructions on building with Autotools, see the old versions of this page. We're not actively supporting the Autotools build any more.

Running <tt>scons</tt> will create a locally-executable version of ASCEND that can be run from the source tree (<tt>pygtk/ascdev</tt> or <tt>tcltk/generic/interface/ascend4</tt>, possibly subject to some environment variable settings. Alternatively, you can install ASCEND and run it from a 'proper' location such as ~/bin/ascend or /usr/bin/ascend, etc. To install files for ASCEND, run

<source lang="a4c">scons install INSTALL_PREFIX=/usr/local</source>

The above will install the PyGTK GUI at /usr/local/bin/ascend and the Tcl/Tk GUI at /usr/local/bin/ascend4. Other sensible values of INSTALL_PREFIX include <tt>~/ascend</tt> or <tt>~</tt>, which will install the PyGTK GUI at ~/ascend/bin/ascend and ~/bin/ascend respectively. These latter ones are good if you don't have root privileges on your system. There are a range of other INSTALL_* options available with our build script, type <tt>scons -qH</tt> to see them. Also note the importance of the <tt>ABSOLUTE_PATHS</tt> option for our build script. Note then when you run '<tt>scons install</tt>' you don't get all the files in the model library, you only get a filter set according to the [[PACKAGE metafiles]] contained in the [[ModelLibrary]].

Some more details on the implementation of the ASCEND build process via SCons is given in [[Developer's_Manual#Build_system]].

== Tcl/Tk GUI ==

In order to build the original Tck/Tk GUI, you need a Tcl/Tk distribution. Recently we have modified ASCEND so that it can run with Tcl/Tk 8.4. Standard Tcl/Tk binary packages can be used, such as those included in Fedora Core 5 (Note, the tcl-devel and tk-devel packages required as well). For Windows they available from ActiveState, see:

http://www.activestate.com/activetcl

At present, detection of Tcl/Tk is not particularly sophisticated. <tt>SConstruct</tt> just looks for <tt>tcl.h</tt> in your standard include path. So you might need to tweak. Check the <tt>scons -h</tt> list of configuration options for more. On Debian-based systems, try something like <tt>scons TCL_CPPPATH=/usr/include/tcl8.4</tt>

== Python interface ==

See PythonWrapper for more information. You will need to have SWIG 1.3.24 or newer and Python 2.4 or newer installed. These are both easy to install for both Windows and Linux.

To run the PyGTK interface requires more dependencies, see the PythonWrapper page for full details.

== Instructions for Linux ==

In general, see [[Prerequisites for Linux]]. You will be using <tt>scons</tt> to build ASCEND. We update these distribution-specific notes at the time that we implement support for that particular distro, so it's possible that if you're using an old distro, you may need to go back and use an old version of the code.

=== Ubuntu 11.10 ===

Tested with thunk {{changeset|3840}} on Ubuntu Oneiric 11.10 32-bit in a VirtualBox machine.

<source lang=sh>
sudo apt-get install subversion swig g++ gfortran python-dev scons flex bison \
graphviz-dev libsundials-serial-dev liblapack-dev libblas-dev ipython \
python-matplotlib
svn co svn://ascend4.org/code/trunk ascend
cd ascend
scons
pygtk/ascdev models/johnpye/testlog10.a4c
</source>

There are some warnings 'Unable to locate theme engine in module_path: "pixmap"' if gtk-engines-pixbuf is not installed, but basically seems to be working fine. If you want to create a binary package suitable for this release,see [[dtar]], but note that currently (Oct 2011) we haven't yet made the necessary changes to related {{src|debian}} file(s). Note that Oneiric comes with SWIG 1.3.40, so no problems with {{bug|517}} at this stage.

Note yet tested: [[IDA]], [[IPOPT]], [[CONOPT]], [[dtar]].

=== Ubuntu 11.04 ===

Tested with trunk {{changeset|3618}} on Ubuntu Natty 11.04 32-bit.

<source lang=sh>
sudo apt-get install subversion swig g++ gfortran python-dev scons flex bison \
graphviz-dev libsundials-serial-dev liblapack-dev tcl8.5-dev tk8.5-dev \
libtktable2.9 libblas-dev ipython python-matplotlib
scons -j2
</source>

Not yet tested: [[CONOPT]], [[IPOPT]], [[IDA]], [[dtar]]. Otherwise all appears fine when running with <tt>pygtk/ascdev</tt>.

To install, try <tt>sudo scons install INSTALL_PREFIX=/usr/local</tt>. After that, you may need to <tt>export LD_LIBRARY_PATH=/usr/local/lib</tt> (or <tt>lib64</tt>) before it runs (with the command <tt>ascend</tt>).

An ASCEND package can be created using <tt>scons dist</tt> and [[dtar]]. This package seems to work fine, except for some missing integration into the new Unity GUI shell.

If IPOPT 3.9.x is also installed (see instructions for 10.04 below) then ASCEND will fail to load external libraries unless the correct LD_LIBRARY_PATH has bee set for IPOPT (/usr/lib/coin:/usr/lib/coin/ThirdParty). It is expected that testing with IPOPT 3.10 will resolve this problem.

=== Ubuntu 10.10 ===

ASCEND compiles fine on Ubuntu 10.10, but you need to use the latest code from the 'trunk' of our [[VersionManagement|subversion repo]]. Subversion r3082 corrects a bug that was preventing use of SCons 2.x, as supplied as part of this distro. Otherwise, required packages are the same as for 10.04, see below. It is recommended that all 'optional' packages are installed at the time of building ASCEND.

For IPOPT, which is an optional component of ASCEND, you should see the build instructions [[IPOPT|here]].

It appears that in Ubuntu 10.10, GraphViz has been upgraded and is not longer compatible with ASCEND. ASCEND should build fine without it, although you will be missing the [[incidence graph]] feature as a result (see {{bug|443}}).

=== Ubuntu 10.04 ===

<s>There is currently a problem with building ASCEND on this platform, due to an error thrown by SWIG version 1.3.40 (ASCEND {{bug|403}}). This error is not seen when running SWIG version 1.3.38 or earlier. ''A temporary workaround is to install the Ubuntu Karmic version if SWIG, available [http://packages.ubuntu.com/karmic/i386/swig/download from here].''</s> (this bug is now fixed in the subversion repo)

For [[IPOPT]], which is an optional solver that can be used by ASCEND, you should additionally see the build instructions [[IPOPT|here]].

To build ASCEND on a clean Ubuntu 10.04 box, the following packages were required (as of trunk r2777):

* subversion
* swig <s>''(see note above)''</s>
* g++
* gfortran
* python-dev
* scons

The following are optional but recommended:

* flex
* bison
* graphviz-dev
* libsundials-serial-dev
* liblapack-dev (used by IPOPT)
* tcl8.5-dev
* tk8.5-dev
* libtktable2.9
* libblas-dev

At runtime, the following packages will add capability to ASCEND:
* ipython
* python-matplotlib

=== Kubuntu 10.04 ===

Building on Kubuntu (KDE) is identical to Ubuntu (GNOME) with the exception that python-gtk2 and python-glade2 must be installed before running the resulting program. This was tested with trunk r3039. At this point in time, building also requires the package libgsl0-dev, because of some dependencies in [[FPROPS]] which need to be removed/made optional.

=== Ubuntu 9.10 ===

Ongoing development of ASCEND is primarily done on this Ubuntu 9.10. Although ASCEND builds against the standard Ubuntu packages for Sundials, you will obtain better functionality with the [[IDA]] solver if you use a version built from latest 2.4.0 source code. The latest release fixes problems with boundary-crossing during integration.

To build ASCEND on a clean Ubuntu 9.10 box, the following packages are required (as of trunk r2667):

* scons
* swig
* python-dev
* scons
* g++
* gfortran

The following packages are optional:

* libsundials-serial-dev
* graphviz-dev
* flex
* bison
* libblas-dev
* tcl8.5-dev
* tk8.5-dev
* tktable2.9

At runtime, the following packages will add capability to ASCEND:

* ipython
* python-matplotlib

For the [[IPOPT]] solver, you will also need to build that separately from source -- see [[IPOPT]] for details.
For the [[CONOPT]] and [[CMSlv]] solvers, you must obtain libconsub3.so, see [[CONOPT]] for details.

=== Ubuntu 9.04 ===

ASCEND should build on this system without any problems, providing the prerequisited that you need are installed. Watch closely the 'scons' output for fleeting comments which may suggest that you're missing a library or a header file, etc. Prereqs should be the same as for Ubuntu 8.04.

Note that after updating to Ubuntu 9.04, you will probably need to rebuild and reinstall things like IPOPT and CONOPT, as gfortran errors seem to arise otherwise.

For the [[IDA]] solver, you may need to add the scons option SUNDIALS_CPPPATH=/usr/include/sundials to make this integrator build correctly.

=== Ubuntu 8.04 LTS ===

ASCEND built fine on Ubuntu 8.0.4 LTS when we last tried it. Numerous prerequisites must be installed, but all of these except IPOPT and CONOPT are currently available from the Ubuntu repositories. Specifically, check libsundials-serial-dev, swig, flex, bison, python-dev, tk-dev, libtktable2.9. Haven't yet tested with CONOPT, so conditional modelling has not yet been checked.

Special treatment for the gfortran compiler is no longer required (as was required for Ubuntu 7.10).

Building of a .deb package can be performed using the [[dtar]] tool included in the source distribution. Usage: scons dist && ~/ascend/tools/dtar/dtar ~/ascend/dist/ascend-0.9.5.116.tar.bz2 ~/ascend/dist/debian.tar.gz.

Ubuntu 8.04 uses GtkSourceView2 instead of the earlier version, with the result that source code highlighting in GEdit using a different <tt>.lang</tt> file. We have written a new version of this file, see the page on [[syntax highlighting]] for more info.

Currently, LyX 1.5 is not available on Ubuntu, and the manual .lyx files require this newer version. So for the moment, you must use <tt>scons WITH_DOC_BUILD=0</tt>.

ASCEND has been runninng on earlier Ubuntu versions, right back to version 5.10.

=== CentOS 5.6 ===

The following steps have been tested using a clean virtual machine created using the CentOS 5.6 net installer for x86_64.

<source lang=sh>
# log in as root...
su
yum install scons subversion tk-devel flex bison gcc-gfortran gcc-c++ python-devel sundials-devel graphviz-devel
wget http://pkgs.repoforge.org/scons/scons-1.2.0-1.el5.rf.noarch.rpm
rpm -i scons-1.2.0-1.el5.rf.noarch.rpm
exit
</source>

Now, back as 'normal' user, obtain a copy of the ASCEND source code from our [[VersionManagement|svn info]] as folder 'ascend' (we tried with trunk revision 3601), then

<source lang=sh>
cd ascend
scons
# ascend now runs via 'pygtk/ascdev'
</source>
If you want to use Matplotlib for plotting in ASCEND with CentOS, try using http://repoforge.org/use/ and

<source lang=sh>
install python-matplotlib python-numpy
</source>

=== Fedora 11 ===

The following steps build ASCEND on a clean Fedora 11 machine (I tested using the Live CD installed to a qemu/kvm virtual machine):

<source lang="sh">su
yum install scons subversion tk-devel flex bison gcc-gfortran gcc-c++ python-devel sundials-devel graphviz-devel swig
scons</source>

<s>Currently (as of 16 Jun 2009), the above results in a error message from g++ while compiling the SWIG output. See {{bug|403}}. Testing on Windows has shown that SWIG 1.3.39 and 1.3.40 have this problem, but 1.3.36 does not have this problem.</s> ''This bug is fixed in the pre-0.9.8 code from our SVN server.''

=== Fedora 9 ===

ASCEND builds without any problems on Fedora 9. You need to install several packages first, including swig, tk-devel, python-devel, scons, flex, bison, gcc-gfortran, gcc-c++. There may be some problems getting the GraphViz and CUnit-related functionality working, let us know if you have problems with that. -- JP, Jun 2008.

You can build an RPM version of ASCEND using <tt>scons dist</tt> followed by <tt>rpm -ta ascend-0.9.5.116.tar.bz2</tt>, providing you have RPM correctly set up. See also [[Building an RPM Package for ASCEND]].

=== OpenSUSE ===

OpenSUSE does not provide an up to date version of SCons (as of this writing, suse 10.2 comes with scons-0.96.91-37). You will need to download a newer version (0.96.93) ([http://sourceforge.net/project/showfiles.php?group_id=30337&package_id=22359 from SF.net].
Do not try 0.97 SCons, as it is not yet supported by the ASCEND SConscripts on the SUSE platform.

''Update (Mar 2010)'' it is suggested that you try latest SCons 1.x if possible, and report your experiences here.

=== Arch Linux ===

To build ASCEND on Arch Linux, follow these steps:

<source lang="a4c">sudo pacman -S gcc gcc-fortran flex bison python scons swig tcl tk graphviz blas</source>

Download and build sundials manually (see [[Prerequisites for Linux]]).

Then follow the [[Building_ASCEND#General_instructions|Genereal instructions]] (running scons and scons install).

If you have problem with SWIG 1.3.40 (scons reports that SWIG package was not found), download older version of [http://www.swig.org SWIG](1.3.38 worked for me, 1.3.24 didn't) and build it manually (./configure, make, make install). Then re-run swig with parameter <tt>SWIG=/usr/local/bin/swig</tt> (or different location where you installed SWIG).

When running ascend script:

<source lang="a4c">LDPATH = [INSTALL_LIB] + GTKLIBPATH + LDPATH
TypeError: can only concatenate list (not "NoneType") to list</source>
<source lang="a4c">LDPATH = [INSTALL_LIB] + GTKLIBPATH + LDPATH</source>
<source lang="a4c">if GTKLIBPATH:
LDPATH = [INSTALL_LIB] + GTKLIBPATH + LDPATH
else:

LDPATH = [INSTALL_LIB] + LDPATH</source>

(found [http://www.mail-archive.com/ascend-sim-users@lists.sourceforge.net/msg00089.html here]).

=== Gentoo ===

Some details for build ASCEND on Gentoo Linux are on a sub-page at [[Building ASCEND/Gentoo]].

== Instructions for Windows ==

The only currently-supported way to build ASCEND on Windows is using MinGW/MSYS and the GCC compiler. There has previously been partial success with the Microsoft compiler tools, but these are not currently actively being used or tested.

=== Windows 7 (64-bit target, with 64-bit Python and 64-bit GTK+) ===

This is now supported! See [[Building ASCEND for 64-bit Windows]]. We haven't yet released a binary though, due to a few minor outstanding tasks to do with building the installer package.

=== Windows 7 (32-bit target) ===

(ongoing!)

* Install 'mingw-get-inst' from http://sourceforge.net/projects/mingw/files/MinGW/, selecting C++ and Fortran compilers as well as MSYS Developer Kit (last item on the list).
* From the Start menu, launch MinGW Shell and use it for any command-line commands in the following.
* <tt>mingw-get install msys-flex msys-bison</tt>
* Install [http://www.python.org/ftp/python/2.7.2/python-2.7.2.msi Python 2.7.2]
* Install [http://prdownloads.sourceforge.net/scons/scons-2.0.1.win32.exe SCons 2.0.1] (be sure to right-click and Run as Administrator)
* Install [http://sourceforge.net/projects/swig/files/swigwin/swigwin-2.0.4/swigwin-2.0.4.zip/download swigwin 2.0.4]
* Install [http://ftp.acc.umu.se/pub/GNOME/binaries/win32/pygtk/2.22/pygtk-all-in-one-2.22.6.win32-py2.7.msi pygtk-all-in-one-2.22.6.win32-py2.7.msi]
* Obtain a copy of the ASCEND source code and untar it to ~/ascend. Best option is to use the 'svn trunk' code, at this stage (Aug 2011).

=== Windows 7 64-bit with 32-bit Python ===

We are currently in the process of testing the ASCEND build on 64-bit Windows 7, running via Virtual Box on a Dell Optiplex 980, with the host OS being Ubuntu 10.04.2 LTS.

* install 'mingw-get-inst', selecting to install C, C++ and Fortran compilers, plus the MSYS Basic System and the MinGW Developer Toolkit.
* install the [http://sourceforge.net/projects/win32svn/files/1.6.15/Setup-Subversion-1.6.15.msi/download win32svn package] from SF.net
* check out the source code from our [[VersionManagement|svn trunk]].
* download [http://www.python.org/download Python 2.7.1] 32-bit version and install with default settings. Python 3 is likely still to cause problems with our code, and we haven't tested it yet. We tried using the 64-bit version of Python 2.7.1, but SCons didn't seem to be able to detect it.
* download [http://sourceforge.net/projects/win32svn/files/1.6.15/Setup-Subversion-1.6.15.msi/download Glade3] and install it.
* download [http://sourceforge.net/projects/scons/files/scons/2.0.1/scons-2.0.1.win32.exe/download SCons 2.0.1] and install it by right-clicking and 'run as administrator' (note that failing to do this might have been the reason that we failed with the 64-bit version of Python, above -- if you get 64-bit Python to work, let us know).
* Add c:\Python27 and c:\Python27\Scripts to your PATH.
* download [http://sourceforge.net/projects/swig/files/swigwin/swigwin-1.3.40/swigwin-1.3.40.zip/download swigwin 1.3.40] and unzip it into your MSYS home directory, then add ~/swigwin-1.3.40 to your PATH.
* download [http://prdownloads.sourceforge.net/gnuwin32/flex-2.5.4a-1.exe?download Flex 2.5.4a] and [http://downloads.sourceforge.net/gnuwin32/bison-2.4.1-setup.exe Bison 2.4.1] from gnuwin32.sf.net, and install them. Add the c:\Program Files (x86)\GnuWin32\bin location to your PATH.
* run scons from within your ASCEND working directory.
* the build process completes successfully

To actually run the resulting binary, you need to also have PyGTK and GTK+ installed on your machine. The best way to do that is via the [http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.22/ new PyGTK All-in-One installer].

The resulting binary can then be run from the MSYS prompt using the following, providing GTK is available in the PATH:
cd ~/ascend
pygtk/ascdev

We have a mechanism for [[building a installer for ASCEND on Windows]] that makes use of NSIS. We are in the process of testing it on Windows 7.

As an aside, the above highlights that it would be desirable to move from the use of libglade to GtkBuilder (as noted {{bug|493}}). We would then be able to use standard PyGTK installers again, rather than needing the huge PyGTK-All-In-One with the optional libglade.dll that it includes.

=== Windows XP with MinGW/MSYS ===

''It is currently suggested that you attempt the same process as given above for Windows 7, instead of that given below.''

The following instructions were tested on 32 bit Windows XP running on a DELL Precision (Core 2 Duo) machine in Nov 2009 and 32 bit Windows VISTA running on a ThinkPad X61 (Core 2 Duo) machine in March 2010.

First install the MinGW/MSYS environment. Download MinGW-5.1.6.exe, and select the basic options plus 'g++' (the C++ compiler). Then download and install MSYS-1.0.11.exe.

Now install Python-2.6.4.msi.

Install pywin32-214.win32-py2.6.exe.

Next, download and install SCons, scons-1.2.0.win32.exe.

Download swigwin-1.3.36 (''later versions are OK'') and unzip it in your root directory (it's just a folder with that name).

Download and install Flex (2.5.4a-1) and Bison (2.4.1) from GnuWin32, installing in the default location.

Download GFortran 'native installer' for MinGW from [http://gcc.gnu.org/wiki/GFortranBinaries]. Our release was dated '2009-04-21'.

With a right-click on the My Computer icon, then in the Advanced tab, add the following to your PATH environment variable (no quotes): ';c:\Python26;c:\Python26\Scripts;c:\swigwin-1.3.36;c:\Program Files\GnuWin32\bin;C:\Program Files\gfortran\bin'. For Windows VISTA system, right-click on the Computer icon, choose Properties. In Advance System Settings, you can configure PATH environment variable.

Install NSIS 2.45.

Download '[[Media:Book.pdf|book.pdf]]' and save it as 'book.pdf' in ~/ascend/doc.

In MSYS, run <tt>scons WITH_DOC_BUILD=0 installer</tt>.

The above will allow you to build ASCEND (and also to build the ASCEND installer using {{src|nsis/installer.nsi}}) but not to run it. For that, you additionally need to complete the following steps:

* Download and install the GTK Glade3 windows installer [http://ftp.gnome.org/pub/GNOME/binaries/win32/glade3/3.6/glade3-3.6.7-with-GTK+.exe]
* Download and install PyGTK [http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.12/pygtk-2.12.1-3.win32-py2.6.exe]
* Download and install PyCairo [http://ftp.gnome.org/pub/GNOME/binaries/win32/pycairo/1.4/pycairo-1.4.12-2.win32-py2.6.exe]
* Download and install PyGObject [http://ftp.gnome.org/pub/GNOME/binaries/win32/pygobject/2.14/pygobject-2.14.2-2.win32-py2.6.exe]

The above Glade3 installer should have added 'c:\Program Files\Gtk+\bin' to your PATH; you can check that if necessary.

To test the installer, it is recommended you remove GTK Glade3, PyGTK, PyCairo, PyGObject, Tcl/Tk and Python. Then run the installer, and it should discover all those missing things and proceed to reinstall them for you.

[[Image:mingw-1.png]]
[[Image:mingw-6.png]]

'''SUNDIALS'''. If you want to use the [[IDA]] integrator (recommended) then you should download and install SUNDIALS. See [[building SUNDIALS on Windows]].

Everything should build and you should end up with a file dist/ascend-{version}.exe which is your 'setup' program. Run that then find ASCEND in your Start menu.

=== MSVC ===

We don't currently support the use of Microsoft compilers. They probably can be made to work, but we don't see any good reason to work on that.

=== Windows / Borland C Builder ===

Some very early efforts to support free Borland 5.5 were made; the core engine basically compiles but there is more work to be done.

== Instructions for Mac ==

=== Mac OS X 10.5 ===

ASCEND runs fine on Mac OS X 10.5, and probably other versions. Currently we haven't completed the job of bundling ASCEND into a convenient distributable form, but the work is now well underway. See [[Porting to Mac]] for details.

There has been no attempt to build or test the Tcl/Tk GUI on Mac at this stage.

== See also ==

* [[Building a Debian package]]
* [[Building an RPM Package for ASCEND]]
* [[Windows Miscellany]]

[[Category:Development]]
[[Category:Documentation]]

Dynamic modelling

2012-02-16T00:42:50Z

BenAllan: /* New syntax */

{{solvers}}{{stub}}
Dynamic modelling in ASCEND is where you solve a system of [http://en.wikipedia.org/wiki/Ordinary_differential_equations ordinary differential equations (ODEs)] or [http://en.wikipedia.org/wiki/Differential_algebraic_equation differential/algebraic equations] for the time-varying values of variables in the model over a certain interval, given the initial conditions of the model. We also refer to this as ''integration''. Dynamic modelling can be done within the ASCEND language providing the relationship between variables and their derivatives can be established.

== About ODE/DAE solvers ==

ODE solvers of the [[LSODE]] and Runge-Kutta class solve problems that can be written:

:<math>\dot{\mathbf{y}} = \mathbf{F} \left(\mathbf{y},t \right)</math>

by projection schemes for <math>\mathbf{y}\left(t+dt\right)</math> which require solving some set of equations based on Jacobian matrix of partial derivatives <math>\mathbf{J} = \partial \mathbf{F} / \partial \mathbf{y}</math> (also referred to as <math>\partial \mathbf{\dot{y}}/\partial \mathbf{y}</math>) being nonsingular. Variants of ODE solvers may allow convergence with limited singularity in <math>\mathbf{J}</math> by using [[singular value decomposition]] (SVD) and assumptions about the properties of <math>\mathbf{F}</math>, but this is not general or robust enough to be used in arbitrary models created with ASCEND.

The ASCEND representation of differential equations allows the more general

:<math>\mathbf{F}\left(\mathbf{y},\mathbf{\dot{y}},t,\mathbf{z}\right)=\mathbf{0}</math>

where <math>\mathbf{z}</math> are apparently non-differential variables (variables that appear in the equations without a corresponding derivative). Considering all variables <math>\mathbf{y}</math>, <math>\mathbf{\dot{y}}</math>, <math>t</math>, <math>\mathbf{z}</math> as algebraic, then the matrix <math>\mathbf{J}</math> can be
calculated analytically (within some tolerance) if the following is true:

:With y fixed, t fixed, and as many z fixed as necessary, a well posed (square, nonsingular) nonlinear problem is obtainable.

This form is precisely the matrix needed at the initial condition, normally. So for each "function evaluation" of [[LSODE]], we solve the nonlinear problem

:<math>\mathbf{F} \left( \mathbf{\dot{y}}, \mathbf{z}_\mathrm{free}\right)=\mathbf{0}</math> such that st. <math>\mathbf{y}</math>, <math>t</math>, <math>\mathbf{y}</math>, <math>\mathbf{z}_\mathrm{fixed}</math> are all fixed

and for each <math>\mathbf{J}</math> needed we take the Jacobian of <math>\mathbf{F}</math> and solve to get a column of sensitivity data. (In
principle this can be accelerated by the method of Curtis, Powell, and Reid{{cite}}, but that so rarely applies we didn't bother).

With the above technique, it may turn out that <math>\mathbf{J}</math> is singular, even under [[SVD]]. This is the usual first indicator of a numerical index problem.

It turns out that in many cases the index problem is even visible structurally in [[QRSlv]] -- meaning there is no feasible way to form <math>\mathbf{F}\left(\mathbf{\dot{y}}, \mathbf{z}_\mathrm{free}\right)</math> by computing all the variables <math>\mathrm{\dot{y}}</math> expected and fixing all the variables <math>\mathbf{y}</math> expected. In this case either the problem is badly posed or a proper ODE problem can be recovered by moving some pair <math>\dot{y}_i, y_i</math> into the set <math>\mathbf{z}</math> and perhaps adding extra constraints obtainable by differentiation of a subset of <math>\mathbf{F}</math>.

DASSL and IDA work around low index problems by solving all model and stepping simultaneously, but for problems typical in chemical engineering (setting pressure
specifications on multistage operations like distillation) DASSL's technique is not enough for reliable solution even if SVD is used under the covers.

So basically, it's great to use DASSL for performance reasons over LSODE and the like. If the reason for using DASSL, IDA and the like is because LSODE '''fails''',
then the modeling approach should be carefully reevaluated.

If the reason for using DASSL/IDA is that they are better at finding initial conditions than LSODE (which has no such functionality), then again the main strength
of ASCEND's primary solvers (getting solutions to hard nonlinear problems) is being overlooked. Ben Allan has heard many times of people using dassl as simply a nonlinear solver and integrating nothing at all.

Finally, now that memory is essentially free, boundary value problem (BVP) solution techniques should be of much greater interest than historically, and it just happens that ASCEND has a very nice BVP library: {{src|models/bvp.a4l}}

== Syntax for dynamic modelling ==

The current method for specifying derivatives is by including the <tt>ivpsystem.a4l</tt> library. Full details are given in ''[http://ascend.cheme.cmu.edu/ftp/pdfPapersRptsSlides/AscendIVP.pdf Design and Use of Dynamic Modeling in ASCEND IV]'' (see our [[publications]] page).

<source lang="a4c">REQUIRE "ivpsystem.a4l";</source>

at the start of your model, then creating a special method

<source lang="a4c">METHOD ode_init;
dx_dt.ode_id := 1;
x.ode_id := 1; (* ie these variables are related with ID '1' *)

dx_dt.ode_type := 2; (* ie 'this is a derivative variable' *)
x.ode_type := 1; (* ie 'this is a differential variable *)

t.ode_type:= -1; (* 'tag' the independent variable *)
END ode_init;</source>

which must be run before sending your model to either [[IDA]] or [[LSODE]] (or a future [[Solvers|solver]]...) for integration.

== New syntax ==

[[Dante Stroe]] recently added support for [[LINK semantics]] that allows this fairly painful syntax to be improved, however the new code is not yet incorporated into the ASCEND 'trunk' (see [[VersionManagement|svn info]]). Based on the LINK structure the following syntax can now be used to define derivative chains, for example:

<source lang="a4c">INDEPENDENT t;
DER(dx_dt,x)</source>

This syntax can be used in either the declarative part of the model, either in the Methods section.

* The '''INDEPENDENT''' keyword adds an independent variable to the solver. While it is possible to store multiple independent variables in the solver data structures, the user is currently limited to only one independent variable, since there is no implementation of partial derivatives. (Implementation-wise, a LINK entry with the 'indepenendent' key and the independent variable itself is created)

* The '''DER''' keyword is used to declare the derivative chains in terms of the declared independent variable. The parameters of DER are the differential variables in decreasing order (ode_type in the previous syntax). The derivative chains declared in DER can be arbitrarily long, however the solver does not handle more than 2nd order derivatives. (Implementation-wise, a LINK entry with the 'ode' key and the differential variable is created)

The following models using the aforementioned syntax have been added:

* {{srcbranch|dante|models/test/ida/singlederiv_wLINK.a4c}}
* {{srcbranch|dante|models/test/ida/twoderiv_wLINK.a4c}}
* {{srcbranch|dante|models/dyn_tank_wLINK.a4c}}
* {{srcbranch|dante|models/johnpye/pendulum_wLINK.a4c}}
* {{srcbranch|dante|models/test/dopri5/dopri5test_wLINK.a4c}}

An inherent weakness of the syntax separating INDEPENDENT from der, as given above, is that in a hierarchically or peerwise composed model, multiple definitions of the same independent variable are possible and may conflict (or this may be by modeler choice, with multiple integrals within an overall model being computed by an IVP solver in different phases of the same simulation process). Several workarounds are possible. All rely on there being a community, or at least a library, standard way of doing things at the modeling level and an IVP solver understanding the convention.
* Syntactically: change the LINK-equivalent usage to be created from DER(dxdt,x,t) rather than DER(dxdt,x(*solver search for independent and insert here*)). Verbose but unambiguous. Solver pre-analysis still must verify that there is only one atom instance (t) that is the target of all DER definitions, even if that instance has multiple names and declarations that may have been merged.
* Typing an ATOM type to enforce that there exactly 1 independent: UNIVERSAL ATOM time_domain REFINES time; All instances of time_domain will automatically be the same. IVP Solvers can examine atom types and identify independent variables as those of type *_domain, eliminating the INDEPENDENT declaration. This solution actually allows multiple domains, and a parameter to an IVP analysis routines is "which domain type" is the independent variable. This would allow switching integrals over space(1-d) and integrals over time in the same model, an interesting capability in Low-Order PDEs. It might also allow interesting analyses in Fourier spaces.

Current DER style doesn't scale to 2 simultaneous independent dimensions: INDEPENDENT x,y; DER(pdUxy,U). In a simultaneous 2-d world, the universal atom approach fails. One can (and probably JP has) argue that PDE models must explicitly represent the grid at the ascend language modeling level, as in the BVP library. We note, however, that NO current production PDE-oriented DSL actually works this way: they all make declarations based on sets and boundaries with arbitrary external definition whose consistency is checked by the solver.

See also
* [[External Integrators]] in the development section.
* [[Initial-value modelling]].
* [[Improved DAE syntax]]
* [[Integrator API]] (how ASCEND interfaces with solvers for dynamic modelling)

[[Category:Documentation]]
[[Category:Syntax]]

Event handling

2012-02-15T23:08:43Z

BenAllan: /* Proposed solution */

{{task}}
''Please add discussion/feedback on the 'discussion' page, restrict this page to description of the problem or a proposed solution/implementation.''

To successfully implement [[integration of conditional models]] is quickly becomes apparent that simple [[boundary detection]] is only a small part of the whole problem. In general, we need to allow for 'events' to occur when a boundary is encountered, for variables to be re-set using abitrary equations and/or expressions, and potentially for difficult ''initial condition problems'' to be solved before integration ([[DAE]]/[[ODE]]) simulation can proceed.

== Use cases ==

Some use cases that we would like to be able to support. These are all continuous-time simulations. We're not looking at adding pure discrete-event simulation at this stage.

* a ''bouncing ball'' that *instantly* reverses its velocity (or v(+) = -v(-) * 0.9, perhaps) when hitting the ground. Note that Leon's approach uses a springy floor, instead of the instant velocity reversal approach. Sometimes we don't want to have to add this extra physics to our simulation.
* ''thermostat controller'': a house has thermal losses, but a heat is attached. Heater turns on when temperature below 18 °C, and turns off when temperature rises above 20 °C. Plot the room temperature as a function of time.
* ''solar house'': in extension to above, add solar energy gain to the thermostat model. on some days, less heating input will be required.
* a tank becoming full and starting to overflow
* a flow rate controller that increments flow in fixed steps when certain thresholds are passed.
* a vessel with an inlet in the side, and an outlet protruding into the pipe from above; if the level is above the outlet, liquid comes out; if the level is below, gas (or nothing) comes out. 'sliding mode' is when a system like this gets stuck on the boundary or oscilates rapidly across it. how do we deal with that? [[User:Kannan]] is our expert on this kind of system.
* annual performance of a solar power plant, including rules like "wait half and hour after sunrise before starting the turbine" and "when storage is full, start dumping heat", using external weather data and demand data to drive the control-system part of the simulation.
* reporting of model 'state' (boolean variables) alongside real variable outputs.

== Implementation issues ==

ASCEND currently supports [[WHEN]] and [[CONDITIONAL]] statements, allowing for models with boundaries and boundary switching behaviour of a specific limited type. ASCEND lacks support for the following:

* 'boundary equations', eg "when temperature = 20 °C, increase flowrate by 1 L/s", or "Vdot(+) = Vdot(-) + 1 {L/s}".
* 'events': things that are executed exactly once, when first arriving at or on a boundary.
* initial condition problems: there is no control over the equations used to reinitialise after a boundary. We just the the IDACalcIC built-in method.
* [[improved DAE syntax|convenient derivative syntax]], eg "der(x) = -x".

Instead, ASCEND allows only equations to be turned off and turned as the solver moves across the boundary. There is no way to trigger and special behaviour or action '''''at''''' the boundary. This means that currently, we can not implement a 'true' bouncing ball model, nor a thermostat model.

=== Modelica implementation ===

The [http://www.modelica.org Modelica language] has some solutions in their syntax documentation<ref>Modelica 3.2 Language Specification, 2010, http://modelica.org/documents/ModelicaSpec32.pdf</ref> to these problems that are worth consideration:

* ''when-equations'' are executed at a boundary
** when-equation are not free-form equations, they are only allowed to be ''x = expr'' assignment statements
** <tt>when..elsewhen</tt> allows queuing/prioritisation of event handlers (queued cases are only allowed when the variables (x) being assigned match in all the nested when-equations
* ''initial equations'' are used to provide a initial condition problem to the solver (but we need to clarify if that only happens at the start of simulation, or at every boundary)
* ''pre(x)'' inside a when-clause returns the value of a simulation variable before the current boundary.
* ''reinit(x, expr)'' re-initialises a variable to a new value upon crossing a boundary
** using ''reinit'' forces Modelica to check that the variable 'x' is a ''state variable'' in the DAE simulation.
** ''reinit'' has the effect of setting variable 'x' to be unknown, and adding a new equation 'x = expr'.
** a standard ''when-equation'' has the effect of simply adding a new ewquation 'x = expr', but not setting 'x' as unknown.
* various sub-expressions trigger boundaries to be 'emitted' from a relation, and added the the solver's boundary list.
* ''noevent(...)'' allows suppression of triggered boundaries
* ''smooth(...)'' forces the solver to treat expressions as continuously differentiable. we assume this is related to boundary suppression.

== gPROMS solution ==

The thesis by Paul Barton<ref>P Barton, 1992. ''[http://yoric.mit.edu/sites/default/files/BartonThesis.pdf Modelling and simulation of combined discrete/continuous processes]'', PhD thesis, MIT.</ref> also has a solution for this problem.

== Other implementations? ==

Some other possible implementations/solutions worth researching:

* MOSILAB webpage<ref>MOSILAB webpage, http://mosim.swt.tu-berlin.de/wiki/doku.php?id=projects:mosilab:home</ref> and paper<ref>J Bastian, C Clauß, O Enge-Rosenblatt and P Schneider, 2010. [http://publica.fraunhofer.de/eprints/urn:nbn:de:0011-n-1355711.pdf MOSILAB - a Modelica solver for multiphysics problems with structural variability], Proceedings of 1st Conference on Multiphysics Simulation - Advanced Methods for Industrial Engineering 2010.</ref>.
* A [http://en.wikipedia.org/wiki/List_of_discrete_event_simulation_software#Open_Source list of discrete event simulation software]

== Proposed solution ==

We don't know how we'll do it. Please give your thoughts on the '''discussion''' page.

A decent explanation of the full design space is in Fishwick<ref>http://www.cee.mtu.edu/~amlan/ce5710/Readings/tax_sim.pdf</ref>

== References ==
<references/>

There are further references in [[integration of conditional models]]

Talk:Event handling

2012-02-15T20:07:38Z

BenAllan: /* Initial condition problems */

''Please add new comments below with a '''<nowiki>==heading==</nowiki>''' and signed beneath using '''<nowiki>~~~~</nowiki>'''. If responding to an earlier comment, prefix your comments with ":" so that they are indented, and sign as before.

== REINIT and PRE ==

One basic implementation of boundary events would be to allow a REINIT statement in addition to the USE statement to exist inside [[WHEN]]..CASE. REINIT statements would be associated with a particular CASE, and whenever a CASE change occurred, it would trigger an ICP to be created and solved.

PRE could then be added to the language. PRE inside a 'normal' relation would trigger an error. PRE inside a REINIT statement would result in a callback to the solver, which would have to keep a copy of variable values before the current boundary.

REINIT x TO -0.9*pre(x);

This statement would set the new value of 'x' and perhaps remove 'x' from the initial value problem. The derivative of x would still need to be solved for, using the dynamic equations in the problem.

[[User:Jpye|Jpye]] 10:55, 11 February 2012 (EST)

== Initial condition problems ==

The major issues we have with event handling currently are
# defining 'edge' events as opposed to 'region conditions'
# flexibly declaring initial condition problems (ICPs)

Our current WHEN syntax defines region conditions pretty well. This means that a boundary is defined, and if the solver crosses that boundary, we have to change our equations, reinitialise the DAE system and then continue.

For 'edge' events, we don't necessarily want to change the equations in our system, we just want to be able to be able to reassign values to certain variables, such that instead of the default state-variable continuity being applied, we can create step changes and other effects.

We are currently missing in ASCEND the idea of ICPs in general, which is a precursor to the above. In DAEs, we have <math>n</math> state variables (variables plus derivatives) plus <math>m</math> algebraic equations. Normal integration time-stepping requires <math<n+m</math> equations. ICP solution requires <math>2n+m</math> equations, because we need to solve the initial derivatives as well as the state variables, plus all the algebraics.

In IDA, the ICP is currently solved by assuming the state variables are fixed, and using the DAE equations to solve the derivatives plus the algebraic variables.

More generally, we should be able to set ICPs both for the truly initial conditions, as well as for each time boundaries are crossed. We could use a [[SWITCH]] statement inside a [[METHOD]] to turn on and off equations in this cases as a first hack. This would require lots of inactive equations to be declared in the model, and in a method <tt>initcond</tt> we could prepare the initial condition problem, and in a method <tt>continue</tt> we could restore the DAE problem. Somewhere inside IDA, then, we would detect a boundary and [[RUN]] <tt>initcond</tt>, then run [[QRSlv]], then run <tt>continue</tt>, the proceed with the integration.

The better solution would allow sometime like the [[CONDITIONAL]] statement, as a way to declare ICP equations. That section would in general need to allow conditional syntax such as supported by [[CMSlv]].

----
Syntactic/semantic background to inform our design process:

An underused feature in ascend is that equations, boundaries, and I think even whens
all have *names* and *subatomic children(flags)*, which can be used.

The current declarative language is focused entirely on declaring an algebraic mathematical description with no time or space dependence. All handling of these variations requires discretization over the *domain* of the independent variable by either the model statement itself (a boundary value formulation) or by the solver (initial value formulation).

The ascend language cannot even *name* the state of all the variables in the model at a given value of the independent variable. I'm not particularly aware of *any* small modeling language which allows you to name the solution of the model at arbitrary times. Several quick-hack languages like gproms/modelica allow you to handle implicitly defined values near 'events'. A more general solution is highly desirable and with the cost of computer memory being essentially zero at this point, there is no reason (any longer) to exclude naming states in the modeling language.

Ben
----

== Proposal 1: a quick hack ==

1. Modify the [[WHEN]] statement so that a single [[RUN]] statement is allow in each CASE:
<source lang=a4c>
WHEN var
CASE TRUE:
RUN mymethod1;
USE eq1;
CASE FALSE:
RUN mymethod2;
USE eq2;
END WHEN;
</source>

2. Modify [[IDA]] such that, after running methods named as above, run a general <tt>initcond</tt> method that would prepare the model for solving the initial condition problem (ICP).

3. Solve the initial problem using [[QRSlv]] or [[CMSlv]] (switchable as an IDA option).

4. Run a general <tt>continue</tt> method to restore the DAE problem, the proceed with IDA integration until the next boundary.

''This approach is flawed because regions are really not the same as events; we should put the 'RUN' statement in the above inside some other kind of statement -- Proposal 4 below.''

== Proposal 2: a better approach ==

1. Modify the declarative syntax to support an INITIAL statement within the declarative section:
<source lang=a4c>
INITIAL
(* here the missing 'n' equations can be added. if omitted, fall back to default IDA behaviour *)
der(x) = 0;
y = 5;
(* also allow SWITCH statements here and maybe even WHEN and CONDITIONAL *)
END INITIAL;
</source>

2. Add an ICP API to the the existing integrator API.

3. Modify the WHEN statement to support 'event' actions as well as 'region' behaviour. We would need to work out if the current WHEN statement is overly flexible; perhaps we need to split it somehow, c.f. Modelica 'if...then' as well as 'when' behaviour. Also note Modelica 'when...elsewhen' prioritisation.
<source lang=a4c>
WHEN y_is_zero
CASE TRUE:
(*...*)
END WHEN;
</source>

3. Modify WHEN statement to support reinitialisation of state variables before the ICP is solved. The problem here is in making sure we can generate consistent ICPs. Do these reinitialisations replace INITIAL equations, or simple reassign values, independently of the ICP solution?

<source lang=a4c>
WHEN y_is_zero
CASE TRUE:
REINIT vel :== -pre(vel);
END WHEN;
</source>

Need to understand whether we need equivalents of Modelica's 'when-equation' as well as this 'reinit' thing.

4. Add the 'pre' so that REINIT statemnts can access previous values of other variables. This would be some kind of callback to the Integrator.

== Proposal 3: EVENT statement ==

We need to put the event handling separate to the WHEN statements. So for a bouncing ball model,

<source lang=a4c>
EVENT x == 0
REINIT xvel :== -pre(xvel);
END EVENT;
</source>

The 'EVENT' statement needs to fire any time that the boolean expression ''was'' previously false, and ''now becomes'' true, i.e. a rising edge. So, what is the difference between the above and the following?

<source lang=a4c>
EVENT x >= 0
REINIT xvel :== -pre(xvel);
END EVENT;
</source>

Not sure if there is a difference? Need to clarify.

== Proposal 4: EVENT statement with RUN ==

This is a modification of Proposal 1.

<source lang=a4c>
EVENT x == 0
RUN mybouncemethod;
END EVENT;
</source>

We could implement this without having to first add support for definition of ICPs, which Proposal 3 definitely requires. Hence this is a quick hack that would let us keep working on the solver algorithms, and let the language features catch up afterwards.

Talk:Event handling

2012-02-15T20:04:36Z

BenAllan: /* Initial condition problems */

''Please add new comments below with a '''<nowiki>==heading==</nowiki>''' and signed beneath using '''<nowiki>~~~~</nowiki>'''. If responding to an earlier comment, prefix your comments with ":" so that they are indented, and sign as before.

== REINIT and PRE ==

One basic implementation of boundary events would be to allow a REINIT statement in addition to the USE statement to exist inside [[WHEN]]..CASE. REINIT statements would be associated with a particular CASE, and whenever a CASE change occurred, it would trigger an ICP to be created and solved.

PRE could then be added to the language. PRE inside a 'normal' relation would trigger an error. PRE inside a REINIT statement would result in a callback to the solver, which would have to keep a copy of variable values before the current boundary.

REINIT x TO -0.9*pre(x);

This statement would set the new value of 'x' and perhaps remove 'x' from the initial value problem. The derivative of x would still need to be solved for, using the dynamic equations in the problem.

[[User:Jpye|Jpye]] 10:55, 11 February 2012 (EST)

== Initial condition problems ==

The major issues we have with event handling currently are
# defining 'edge' events as opposed to 'region conditions'
# flexibly declaring initial condition problems (ICPs)

Our current WHEN syntax defines region conditions pretty well. This means that a boundary is defined, and if the solver crosses that boundary, we have to change our equations, reinitialise the DAE system and then continue.

For 'edge' events, we don't necessarily want to change the equations in our system, we just want to be able to be able to reassign values to certain variables, such that instead of the default state-variable continuity being applied, we can create step changes and other effects.

We are currently missing in ASCEND the idea of ICPs in general, which is a precursor to the above. In DAEs, we have <math>n</math> state variables (variables plus derivatives) plus <math>m</math> algebraic equations. Normal integration time-stepping requires <math<n+m</math> equations. ICP solution requires <math>2n+m</math> equations, because we need to solve the initial derivatives as well as the state variables, plus all the algebraics.

In IDA, the ICP is currently solved by assuming the state variables are fixed, and using the DAE equations to solve the derivatives plus the algebraic variables.

More generally, we should be able to set ICPs both for the truly initial conditions, as well as for each time boundaries are crossed. We could use a [[SWITCH]] statement inside a [[METHOD]] to turn on and off equations in this cases as a first hack. This would require lots of inactive equations to be declared in the model, and in a method <tt>initcond</tt> we could prepare the initial condition problem, and in a method <tt>continue</tt> we could restore the DAE problem. Somewhere inside IDA, then, we would detect a boundary and [[RUN]] <tt>initcond</tt>, then run [[QRSlv]], then run <tt>continue</tt>, the proceed with the integration.

The better solution would allow sometime like the [[CONDITIONAL]] statement, as a way to declare ICP equations. That section would in general need to allow conditional syntax such as supported by [[CMSlv]].

----
Syntactic/semantic background to inform our design process:

An underused feature in ascend is that equations, boundaries, and I think even whens
all have *names* and *subatomic children(flags)*, which can be used.

The current declarative language is focused entirely on declaring an algebraic mathematical description with no time or space dependence. All handling of these variations requires discretization over the *domain* of the independent variable by either the model statement itself (a boundary value formulation) or by the solver (initial value formulation).

The ascend language cannot even *name* the state of all the variables in the model at a given value of the independent variable. I'm not particularly aware of *any* small modeling language which allows you to name the solution of the model at arbitrary times. Several quick-hack languages like gproms/modelica allow you to handle implicitly defined values near 'events'. A more general solution is highly desirable and with the cost of computer memory being essentially zero at this point, there is no reason (any longer) to exclude naming states in the modeling language.

----

== Proposal 1: a quick hack ==

1. Modify the [[WHEN]] statement so that a single [[RUN]] statement is allow in each CASE:
<source lang=a4c>
WHEN var
CASE TRUE:
RUN mymethod1;
USE eq1;
CASE FALSE:
RUN mymethod2;
USE eq2;
END WHEN;
</source>

2. Modify [[IDA]] such that, after running methods named as above, run a general <tt>initcond</tt> method that would prepare the model for solving the initial condition problem (ICP).

3. Solve the initial problem using [[QRSlv]] or [[CMSlv]] (switchable as an IDA option).

4. Run a general <tt>continue</tt> method to restore the DAE problem, the proceed with IDA integration until the next boundary.

''This approach is flawed because regions are really not the same as events; we should put the 'RUN' statement in the above inside some other kind of statement -- Proposal 4 below.''

== Proposal 2: a better approach ==

1. Modify the declarative syntax to support an INITIAL statement within the declarative section:
<source lang=a4c>
INITIAL
(* here the missing 'n' equations can be added. if omitted, fall back to default IDA behaviour *)
der(x) = 0;
y = 5;
(* also allow SWITCH statements here and maybe even WHEN and CONDITIONAL *)
END INITIAL;
</source>

2. Add an ICP API to the the existing integrator API.

3. Modify the WHEN statement to support 'event' actions as well as 'region' behaviour. We would need to work out if the current WHEN statement is overly flexible; perhaps we need to split it somehow, c.f. Modelica 'if...then' as well as 'when' behaviour. Also note Modelica 'when...elsewhen' prioritisation.
<source lang=a4c>
WHEN y_is_zero
CASE TRUE:
(*...*)
END WHEN;
</source>

3. Modify WHEN statement to support reinitialisation of state variables before the ICP is solved. The problem here is in making sure we can generate consistent ICPs. Do these reinitialisations replace INITIAL equations, or simple reassign values, independently of the ICP solution?

<source lang=a4c>
WHEN y_is_zero
CASE TRUE:
REINIT vel :== -pre(vel);
END WHEN;
</source>

Need to understand whether we need equivalents of Modelica's 'when-equation' as well as this 'reinit' thing.

4. Add the 'pre' so that REINIT statemnts can access previous values of other variables. This would be some kind of callback to the Integrator.

== Proposal 3: EVENT statement ==

We need to put the event handling separate to the WHEN statements. So for a bouncing ball model,

<source lang=a4c>
EVENT x == 0
REINIT xvel :== -pre(xvel);
END EVENT;
</source>

The 'EVENT' statement needs to fire any time that the boolean expression ''was'' previously false, and ''now becomes'' true, i.e. a rising edge. So, what is the difference between the above and the following?

<source lang=a4c>
EVENT x >= 0
REINIT xvel :== -pre(xvel);
END EVENT;
</source>

Not sure if there is a difference? Need to clarify.

== Proposal 4: EVENT statement with RUN ==

This is a modification of Proposal 1.

<source lang=a4c>
EVENT x == 0
RUN mybouncemethod;
END EVENT;
</source>

We could implement this without having to first add support for definition of ICPs, which Proposal 3 definitely requires. Hence this is a quick hack that would let us keep working on the solver algorithms, and let the language features catch up afterwards.

Event handling

2012-02-15T19:49:18Z

BenAllan: /* Proposed solution */

{{task}}
''Please add discussion/feedback on the 'discussion' page, restrict this page to description of the problem or a proposed solution/implementation.''

To successfully implement [[integration of conditional models]] is quickly becomes apparent that simple [[boundary detection]] is only a small part of the whole problem. In general, we need to allow for 'events' to occur when a boundary is encountered, for variables to be re-set using abitrary equations and/or expressions, and potentially for difficult ''initial condition problems'' to be solved before integration ([[DAE]]/[[ODE]]) simulation can proceed.

== Use cases ==

Some use cases that we would like to be able to support. These are all continuous-time simulations. We're not looking at adding pure discrete-event simulation at this stage.

* a ''bouncing ball'' that *instantly* reverses its velocity (or v(+) = -v(-) * 0.9, perhaps) when hitting the ground. Note that Leon's approach uses a springy floor, instead of the instant velocity reversal approach. Sometimes we don't want to have to add this extra physics to our simulation.
* ''thermostat controller'': a house has thermal losses, but a heat is attached. Heater turns on when temperature below 18 °C, and turns off when temperature rises above 20 °C. Plot the room temperature as a function of time.
* ''solar house'': in extension to above, add solar energy gain to the thermostat model. on some days, less heating input will be required.
* a tank becoming full and starting to overflow
* a flow rate controller that increments flow in fixed steps when certain thresholds are passed.
* a vessel with an inlet in the side, and an outlet protruding into the pipe from above; if the level is above the outlet, liquid comes out; if the level is below, gas (or nothing) comes out. 'sliding mode' is when a system like this gets stuck on the boundary or oscilates rapidly across it. how do we deal with that? [[User:Kannan]] is our expert on this kind of system.
* annual performance of a solar power plant, including rules like "wait half and hour after sunrise before starting the turbine" and "when storage is full, start dumping heat", using external weather data and demand data to drive the control-system part of the simulation.
* reporting of model 'state' (boolean variables) alongside real variable outputs.

== Implementation issues ==

ASCEND currently supports [[WHEN]] and [[CONDITIONAL]] statements, allowing for models with boundaries and boundary switching behaviour of a specific limited type. ASCEND lacks support for the following:

* 'boundary equations', eg "when temperature = 20 °C, increase flowrate by 1 L/s", or "Vdot(+) = Vdot(-) + 1 {L/s}".
* 'events': things that are executed exactly once, when first arriving at or on a boundary.
* initial condition problems: there is no control over the equations used to reinitialise after a boundary. We just the the IDACalcIC built-in method.
* [[improved DAE syntax|convenient derivative syntax]], eg "der(x) = -x".

Instead, ASCEND allows only equations to be turned off and turned as the solver moves across the boundary. There is no way to trigger and special behaviour or action '''''at''''' the boundary. This means that currently, we can not implement a 'true' bouncing ball model, nor a thermostat model.

=== Modelica implementation ===

The [http://www.modelica.org Modelica language] has some solutions to these problems that are worth consideration:

* ''when-equations'' are executed at a boundary
** when-equation are not free-form equations, they are only allowed to be ''x = expr'' assignment statements
** <tt>when..elsewhen</tt> allows queuing/prioritisation of event handlers (queued cases are only allowed when the variables (x) being assigned match in all the nested when-equations
* ''initial equations'' are used to provide a initial condition problem to the solver (but we need to clarify if that only happens at the start of simulation, or at every boundary)
* ''pre(x)'' inside a when-clause returns the value of a simulation variable before the current boundary.
* ''reinit(x, expr)'' re-initialises a variable to a new value upon crossing a boundary
** using ''reinit'' forces Modelica to check that the variable 'x' is a ''state variable'' in the DAE simulation.
** ''reinit'' has the effect of setting variable 'x' to be unknown, and adding a new equation 'x = expr'.
** a standard ''when-equation'' has the effect of simply adding a new ewquation 'x = expr', but not setting 'x' as unknown.
* various sub-expressions trigger boundaries to be 'emitted' from a relation, and added the the solver's boundary list.
* ''noevent(...)'' allows suppression of triggered boundaries
* ''smooth(...)'' forces the solver to treat expressions as continuously differentiable. we assume this is related to boundary suppression.

== Proposed solution ==

We don't know how we'll do it. Please give your thoughts on the '''discussion''' page.
We need some external references here

(link to modelica standard)

(link to Barton thesis (gproms) which had event syntax)

Building ASCEND for 64-bit Windows

2012-02-09T22:55:36Z

BenAllan:

There are a number of barriers to building ASCEND on 64-bit Windows:

* 'Standard' MinGW does not build 64-bit executables, so we need to use the MinGW-w64 compiler, which is a bit new.
* We need to switch to a true 64-bit Python in order to run 64-bit ASCEND.
* PyGTK for 64-bit may have some bugs (http://www.daa.com.au/pipermail/pygtk/2009-July/017278.html)
* Windows 64 uses 8-byte pointers (long long) which our code hasn't had to deal with up to now. {not true: we did it routinely in the 1990s-- but there were no WIN 64 bit ports in the 90s. The DEC machines actually supported both 4 and 8 byte pointers and we built both ways (appropriately autoconf'd) without issues. Ben's default Linux is always 64 bit; he really should set up a buildbot for it.}

This page records our progress on getting up and running.

== Steps to date ==

* install MSYS bundle to c:\msys as instructed [http://sourceforge.net/apps/trac/mingw-w64/wiki/MSYS here] (I chose 'MSYS-20111123.zip')
* install MinGW-64 bundle to c:\mingw64 as instructed (we used [http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Automated%20Builds/mingw-w64-bin_i686-mingw_20111220.zip/download mingw-w64-bin_i686-mingw_20111220.zip]
* From the MSYS prompt, edit /etc/fstab so that 'c:/MinGW64' is mapped to '/mingw'
* install 64-bit Python 2.7.2
* download and install the [http://www.sliksvn.com/en/download SlikSvn 64-bit client].
* append /c/Python27 and /c/Python27/Scripts and SlikSvn to the PATH in MSYS. Also, set an environment variable HOST_PREFIX for the MinGW-w64 compiler (to be used by our SCons script). A good way is by creating the file <tt>~/.profile</tt>
<pre>export PATH="$PATH:/c/Python27:/c/Python27/Scripts:/c/Program Files/SlikSvn/bin"
export HOST_PREFIX=x86_64-w64-mingw32</pre>
* download and extract source tarball for SCons 2.1.0. Build via <tt>python setup.py bdist_wininst</tt> then install resulting .exe in dist subfolder.
* install 'findutils' by unpacking [http://sourceforge.net/projects/mingw/files/MSYS/Base/findutils/findutils-4.4.2-2/findutils-4.4.2-2-msys-1.0.13-bin.tar.lzma/download findutils-4.4.2-2-msys-1.0.13-bin.tar.lzma] and unpacking into c:\msys

Things we need to work on:

* can we set up a MinGW/MinGW-w64 combined build environment and build both 32- and 64-bit versions on that same machine? Can Python 32-bit and 64-bit coexist? Can we install 32- and 64-bit versions of all the Python modules, and GTK as well?
* rather than using the big bundle MSYS that is provided by the MinGW-w64 project, we should try to use 'standard' MinGW-get-inst for the MSYS portion, and load MinGW-w64 on top of that. Makes obtaining minor utilities like 'find' and 'autoconf' much easier.
* our build tools can be 32-bit, even if the build target is 64-bit.

== Test suite ==

* The CUnit test suites seem to be basically working. We have made changes to CUnit and currently require that you access the svn trunk version of CUnit for ASCEND testing. A new CUnit release is planned.
* Failing test cases:
** compiler_autodiff (issue with a non-null pointer in line 198)
** compiler_bintok (program hangs! possibly just a configuration issue? looks like the parser is waiting for input from stdin)
** compiler_blackbox (lacking error code in return from parse. not Win64 specific)

Check the current build status on our [[buildbot]].

== Python bindings ==

Before MinGW-w64 can link to Python27.dll, you need to download, build, and install a utility called 'gendef' which builds library *.def files that MinGW-w64 can use. The python27.lib file distributed with Python doesn't work with MinGW-w64 (or maybe even for MinGW32?). To build gendef, we used revision r4724 from [http://mingw-w64.svn.sourceforge.net/viewvc/mingw-w64/trunk/mingw-w64-tools/gendef/ here] (click 'download GNU tarball').

* ./configure --host=x86_64-w64-mingw32 --prefix=/mingw
* make -j4
* make install

Next, run gendef as follows. Using Windows Explorer, copy the file c:\Windows\System32\Python27.dll into c:\Python27\Libs. Then, in MSYS,

* cd /c/Python27/Libs
* gendef Python27.dll
* mv Python27.lib OLD-Python27.lib ''(just in case?)''

Firstly, as per [http://bugs.python.org/issue4709 python bug 4709], in <tt>c:\Python26\include\pyconfig.h</tt>, you need to move the following lines,

<source lang=c>
#ifdef _WIN64
#define MS_WIN64
#endif
</source>

further up the file, to just before the <tt>#ifdef _MSC_VER</tt> in line 107.

''Earlier, we thought that you also needed to patch the Python include file 'modsupport.h'. We don't think that's necessary now, if the above patch is made.''

Install SWIGWIN 1.3.40 to c:\MinGW\swigwin-1.3.40 and add it to your MSYS PATH. Note that ({{bug|494}}) there is currently a bug in SWIG 2.x that prevents us from using it. It looks like that SWIG bug is fixed in their code, but we have to wait for the SWIG 2.0.5 release.

You can now build the ASCEND Python module, <tt>ascpy</tt>. It seems to work, but as of writing, there is a crash in the GUI when instantiating a model. It might be that there are still some errors in relation with 64-bit data types, possibly in the {{srcdir|ascxx}} code. With the above, <tt>./test.py TestSolver.testsunpos6</tt> loads and solves a model correctly! Python bindings at least partly operational! Also, <tt>pygtk/ascdev models/test/ipopt/test6.a4c</tt> seems to work too, if the runtime dependencies listed below are first installed.

=== Notes about Python with MinGW-w64 ===

There seem to be warnings on the net about MinGW and MinGW-w64 used with SWIG. It has always worked fine for us on Win32, but maybe there are new issues arising. To test this, here is a simple 'hello world' example SWIG module. It works on Ubuntu 11.10 32-bit, and builds fine on Win7 64-bit, but fails with a segfault when exiting.

'''[[Media:swigtest.tar.gz|swigtest.tar.gz]]''' (900 byte tarball)

MinGW-w64 can build (without SWIG) against Python 2.7 for at least trivial bindings... we can prove it. A simple example that takes a string, prints it, and calculates its length, seems to work fine:

'''[[Media:pytest.tar.gz|pytest.tar.gz]]''' (1.1k tarball)

Both of the above tests work fine if the patch from [http://bugs.python.org/issue4709 python bug 4709] is applied to your installed Python pyconfig.h header file.

Other pages on MinGW with Python:
* http://sebsauvage.net/python/mingw.html (32-bit version)
* http://boodebr.org/main/python/build-windows-extensions

== Cunit ==

* use SVN code from the branch 'mingw64':
** cd
** svn co https://cunit.svn.sourceforge.net/svnroot/cunit/branches/mingw64 cunit
** cd cunit
* <tt>./configure --prefix=/mingw --host=x86_64-w64-mingw32 --build=mingw32</tt>
* make install

== SUNDIALS ==

SUNDIALS is used by the [[IDA]] solver in ASCEND.

* <tt>./configure --host=x86_64-w64-mingw32 --prefix=/mingw</tt>
* <tt>make -j4</tt>
* <tt>make install</tt>

== IPOPT ==

* download and extract the 'findutils' lzma tarball from [http://sourceforge.net/projects/mingw/files/MSYS/Base/findutils/findutils-4.4.2-2/findutils-4.4.2-2-msys-1.0.13-bin.tar.lzma/download here]; put the extract 'find.exe' and 'xargs.exe' into c:/msys/bin.
* download the source tarball for IPOPT 3.10.1
* <tt>cd ThirdParty/Blas && ./get.Blas </tt> (note that on my system I had to edit the URL in the <tt>get.Blas</tt> script to use "http:" instead of "ftp:")
* <tt>cd ThirdParty/Metis && ./get.Metis</tt>
* <tt>cd ThirdParty/Mumps && ./get.Mumps</tt>
* <tt>cd ThirdParty/Lapack && ./get.Lapack</tt>
* <tt>./configure --host=x86_64-w64-mingw32 --prefix=/mingw</tt>
* <tt>make -j4</tt>
* <tt>make install</tt>

If the install works OK you should have some /mingw/libcoin* and /mingw/libipopt.a files.

This will build you a static IPOPT solver. There isn't a way to build a DLL of IPOPT with MinGW yet, apparently.

To get <tt>scons</tt> to detect this build of IPOPT, use

scons --config=force -j4 IPOPT_LIBPATH=/mingw/lib IPOPT_PREFIX=/mingw IPOPT_LIBS=ipopt,coinmumps,coinmetis,coinlapack,coinblas,gfortran,stdc++

The above seems to work fine, except that it results in a dynamic link to <tt>libgfortran-3.dll</tt> that must be satisfied at runtime in order for IPOPT to work. Possibly a solution will be

F77FLAGS="-static" ./configure --host=x86_64-w64-mingw32 --prefix=/mingw

Wait and see if that works...

== GDB ==

* Download the GDB package from the MinGW-64 site [https://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/gdb/ here] (we chose [http://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/gdb/x86_64-w64-mingw32-gdb-7.1.90.20100730.zip/download x86_64-w64-mingw32-gdb-7.1.90.20100730.zip])
* Building GDB from source tarball version 7.3.1 worked OK but the resulting GDB didn't recognise/load symbols from the running executable. So download the MinGW-64 pre-compiled version instead.

== Runtime requirements ==

To actually run the GUI resulting from the above build, you still need to install GTK+, PyGTK, PyCairo, PyGObject. Get the amd64 py2.7 packages from this page:

* http://ftp.gnome.org/pub/GNOME/binaries/win64/gtk+/2.22/
** get the GTK+ 2.22 runtime ''''bundle''''
** extract to c:\GTK
** make sure you don't have any other GTK installations on your path

* http://www.lfd.uci.edu/~gohlke/pythonlibs
** <tt>py2cairo-1.10.0.win-amd64-py2.7.‌exe</tt>
** <tt>pygobject-2.28.6.win-amd64-py2.7.‌exe</tt>
** <tt>pygtk-2.22.0.win-amd64-py2.7.‌exe</tt>

To test the above:
* c:\GTK\bin must be in your PATH when attempting to run anything that uses GTK.
* gtk-demo.exe should work and pop up a window with some GUI demos
* start up Python and try
<source lang=py>import gtk
w = gtk.Window()
w.add(gtk.Label("hello"))
w.show_all()
</source>

Some helpful diagnostics for finding out why 'import gtk' gives errors in some cases: (in my case, I needed to add c:/GTK/bin to the START of my PATH because of a conflicting ZLIB1.DLL earlier in my PATH.
* http://gramps-project.org/wiki/index.php?title=ImportError:_DLL_load_failed

Some optional components that will allow the ASCEND GUI to do more:
* http://www.lfd.uci.edu/~gohlke/pythonlibs/
** IPython
** NumPy
** Matplotlib

== Creating the installer ==

A number of changes are required to produce an installer for the 64-bit version of ASCEND:
* make sure no WoW3264Node confusions arise when trying to install 64-bit ASCEND on 64-bit Windows.
* it should still be possible to install 32-bit ASCEND on 64-bit Windows.
* ensure package works without gfortran, libstdc++, libgcc being present on the system
* make sure that installed versions of GTK/Python etc are 64 bit and not 32-bit.
* are there any issues with MSVCR90.DLL not being present? PyGTK seems to depend on it.
* what happens when you try to install on Windows 32?
* include all required dependencies in the package: total size would be +~45MB (minus compression savings, minus optimisations from removing unneeded bits of GTK+?

Ben Allan

2011-03-28T20:02:50Z

BenAllan:

Ben Allan is a former ASCEND GSOC mentor and is still episodically involved in development as his personal time allows.

His particular primary interests are in:

* refactoring the globals out of ascend C code.
* to make it thread-safe and embeddable.
* to make it easily integrated with other languages, and vice versa.
* to make it easier to liberate models from ascend once they are developed.

[[Category:ASCEND Contributors]]

Student projects

2011-03-28T19:57:54Z

BenAllan:

Here are some possible projects for students wanting to participate in the ASCEND project. These could be suitable for [http://code.google.com/soc GSOC] projects, final-year theses in Engineering studies, research projects, etc. For contact details, see the [[Support]] page.

The following exercises are no longer part of the application process but may be interesting reading [[OpenMP Exercise]], [[ANTLR exercise]].
Submitting patches to fix bugs in the tracker or working on a new feature ahead of GSOC11 are the best ways to support an application.

Please contact John Pye instead of Ben Allan for any item below listing Ben Allan as contact. Ben is not mentoring for 2011, though he may be helpful by email after GSOC starts.

See also [[Development Activities]].

'''GSOC applicants, please also read our suggestions for [[GSOC2011]].'''

= Active projects =

== [[Integration of conditional models]] ==

Dynamic models with switching behaviour are a common need in much engineering work. Examples from mechanical engineering include non-return valves, on/off valves, laminar/turbulent transitions, user demand for hot water, sunlight dropping while clouds pass, etc.
The [[IDA]] solver provides support for detection of boundaries during the solution of the [[DAE]] system. These boundaries can be used to stop the solver, and to implement switching conditions, for example to switch from laminar flow to turbulent flow once the speed gets to a certain threshold. This problem requires digging deeply into the [[conditional modelling]] data structures in ASCEND and re-wiring them for use with dynamic simulations.

* Contact person: [[John Pye]]
* Languages: C

Current activity: [[Leon Kwek]] is working on this project as a final-year engineering honours project [http://cecs.anu.edu.au at ANU].

== ABsolver integration ==

[[ABsolver]] is an interesting new kind of solver that uses a [http://en.wikipedia.org/wiki/Boolean_satisfiability_problem SAT] solver to drive the solution to a [[conditional modelling]] problem. We would like to work together with the authors of ABsolver to connect that solver to our modelling environment, and then test it on a range of engineering problems. It's not sure yet if some tricks will be required to make the SAT problem formulation compatible with ASCEND's modelling language, so there's a bit of architecture/design required as part of this problem.

* Contact person: [[John Pye]], Andreas Bauer (one of the ABsolver developers)
* Level of difficulty: not sure yet
* Languages: C, C++
* Priority: Low/Medium

Current activity: [[Franc Ivankovic]] is working on this an a final-year engineering honours project [http://cecs.anu.edu.au/ at ANU].

== QRCUDA ==

This project involves writing a parallelised version of [[QRSlv]] that works with CUDA GPGPUs.

* Contact person: John Pye
* Level of difficulty: high

Current activity: [[User:Arash]] from Murdoch University, Western Australia, is working on this project.

== RADAU5 ==

ASCEND currently has a good supply of multi-step solvers for [[ODE]]/[[DAE]] systems, namely [[LSODE]] and [[IDA]], but for single-step solvers, only [[DOPRI5]] (explicit solver for non-stiff problems) is present. This project involves the addition of the [[RADAU5]], an implicit solvers for stiff problems. RADAU5 is a mature solver, and connecting it is not expected to be overly difficult, but it will be a useful addition for a certain class of dynamic problems, and also useful for benchmarking.

* Contact person: John Pye, Kannan Moudgalya
* Level of difficulty: medium

Current activity: [[Shrikanth Ranganadham]] from IIT-Bombay is working on this project as part of a Masters degree in the Chemical Engineering Department.

= New projects =

== Dynamic modelling improvements ==

This project would build on the progress with [[dynamic modelling]] by [[User:DanteStroe|Dante]] in GSOC2009. This year, we'd like to thoroughly incorporate the new [[LINK syntax]] into the integrator API, and and make further changes to the ASCEND language to make dynamic modelling more 'natural', hopefully getting as far as simple <tt>der(x) = x + y</tt> expressions being possible. The changes to the integrator API would need to be incorporated into all the current [[ODE]]/[[DAE]] solvers, too, as part of this work. Some reusable elements would be identified, and may be incorporated into libascend.

* Contact person: [[John Pye]]
* Level of difficulty: High
* Priority: High
* Must know: numerical methods
* Languages: C, plus ideally some experience of lex/yacc

== Debugging tools for DAE modelling ==

We would like to implement tools that make it easier to determine degrees-of-freedom problems for inital value problems, and possibly implement index reduction into ASCEND. This project is probably contingent on completion of the [[#Dynamic modelling improvements]] project above, so we list this idea here as a future placeholder.

* Contact person [[John Pye]]
* Level of difficulty: High
* Priority: Medium
* Must know: numerical methods, differential equations, graph theory
* Languages: C

== Renewable energy system modelling ==

A student with strong engineering thermodynamics skills is needed to work on expanding support for energy systems modelling in ASCEND (see [[Renewable_energy_systems_modelling|here]] and [[Energy_system_modelling_with_ASCEND|here]]). We would like as a minimum to be able to perform annual simulations of domestic solar hot water systems of a variety of types. If time permits, we would like to move on to dynamic simulations of large-scale solar thermal power stations, including trough, dish, and tower systems. Initially, models based on correlations and equations from published journal papers are the goal. Good textbooks containing the necessary background theory would be Çengel ''Thermodynamics'' (Rankine cycles, etc) and Duffie & Beckman ''Solar Engineering of Thermal Processes'' (solar collectors, solar radiation, etc).

* Contact person: [[John Pye]]
* Level of difficulty: Medium
* Priority: High
* Must know: Thermodynamics, Heat transfer
* Languages: C, ASCEND

== GUI improvements ==

Our PyGTK-based GUI for ASCEND now implements are fairly usable subset of the functionality originally provided by the Tcl/Tk GUI. But there are some rusty bits and some buggy bits, and some functionality that still remains to be implemented. This project would require a student with a bit of a flair and/or interest in human interface design (eg see the [http://library.gnome.org/devel/hig-book/stable/ GNOME HIG]), as well as hopefully a little bit of experience using [[Other_modelling_tools|other comparable software packages]], to go in and look at the old Tcl/Tk GUI, look at the new PyGTK GUI and then go ahead and add or fix up the missing pieces, while also fixing some of the [http://tinyurl.com/ascbugs1 various bugs in the currently-implemented stuff].

* Contact person: [[John Pye]]
* Level of difficulty: Medium/Low
* Priority: High
* Must know: usability principles
* Languages: Python, C (and learn to read Tcl/Tk code)

== [[Canvas-based_modeller_for_ASCEND|Canvas-based modelling]], continued ==

Our recent GSOC project on this topic made excellent progress, and it is now possible to construct and solve simple models uby 'wiring up' blocks and setting the parameters therein. However, more work is needed before this tool becomes generally usable. This includes adding support for customised block appearance (so that the canvas looks more like a process flow diagram), and consideration of some nitty-gritty issues relating to debugging of models with closed circulation loops, which naturally involve redundant equations. We'd really like someone from an engineering background to take this one on, if possible, because we also need to develop a library of suitable canvas components, such as turbines, pumps, etc. Another area of work is specification of flow streams. When dealing with fully generic models of things like turbines, etc, we need to be able to specify the fluids in the system in some way that is independent of the blocks being sketched out. Suitable architecture for that needs to be discussed and designed.

* Contact person: [[John Pye]]
* Level of difficulty: medium
* Must know: computer graphics, human-computer interface design, graph theory
* Priority: High
* Languages: Python, C/C++.

== Improvements to the Conditional Modelling syntax ==

ASCEND provides support for [[Conditional modelling]] in the form of language constructs and a solver called [[CMSlv]]. Unfortunately the syntax available for conditional modelling is unintuitive. It could be improved by a student willing to delve into the dark corners of the ASCEND compiler and willing to learn about the Flex and Bison parser/compiler tools. Further work on this project could include a rigorous test-suite to demonstrate that all aspects of the conditional model parser and corresponding solver are working OK. Additional further might include enhancements to the graphical interface to make it more obvious to the user when parts of the model are switched on and off as a result of changes in IF or WHEN statements, or alternatively completion of the conditional modelling support for the dynamic modelling solver [[IDA]]. This is another item that would benefit from a [[New Compiler]] effort.

* Contact person: [[John Pye]], [[Art Westerberg]]
* Level of difficulty: medium
* Priority: High
* Languages: Flex/Bison, C

== BonMin integration ==

For [[conditional modelling]] problems, ASCEND currently offers [[CMSlv]] solver, developed by Vicente Rico-Ramirez. To diversify our offerings for solving these kinds of problems, we would like to also add support for [https://projects.coin-or.org/Bonmin BonMin], the MINLP solver offered by the COIN-OR project. The BonMin API seems to have some notable differences from the API provided by ASCEND, so we anticipate that providing the suitable adapter routines will be a significant part of the project

* Contact person: [[John Pye]]
* Level of difficulty: hard
* Must know: numerical methods, operations research
* Languages: C.
* Priority: Medium/High

== Bug Squashing ==

We've got a [http://ascendbugs.cheme.cmu.edu/ big long list] of bugs and feature requests (as well as [http://ascendbugs.cheme.cmu.edu/roadmap_page.php a shortlist]) that a student could certainly work on with success. Many of the bugs we fairly easily fixed and just need a little time. Someone with the right C/C++/Python programming background plus understanding on numerical methods and hopefully some understanding of compiler design and/or GUI design could really make a difference to ASCEND. (see also [[#Packaging for Mac]])

* Contact person: [[John Pye]]
* Level of difficulty: variable, depends on the bugs you choose to fix
* Must know: numerical methods
* Languages: C, and then possibly Python, C++, Flex/Bison, SWIG, Tcl/Tk, PyGTK,...
* Priority: Medium/High

== Model Export Engine Experiments (meee!) ==

A number of the other projects on this page are concerned with converting a model into some format appropriate for use with another tool. There are actually 2 kinds of objects both ambiguously known as ASCEND models:

* an ascend TypeDescription: a lit of statements that must be interpreted somehow to derive a data tree (Instance) in memory.
* an Instance data tree (which, in principle, may contain references to unexecuted statements from the TypeDescription or may be 'completed').

Potential approaches

* Conversion of C TypeDescriptions to equivalent classes in some other language is the most general form of model reuse, but requires careful implementation of the conversion operation. A general solution would be to create, or expose in a convenient form, visitor functionality over a self-consistent list of related TypeDescriptions for type-translation plugins to convert to other languages. In the compiler science world, the ascend TD is most related to an AST.

* Conversion of ascend model source via an independent parser to another language. This approach 'reinvents' the ASCEND AST and grammar, but may then be much more translator friendly-- e.g. Java or other tools could be used for implementation with no direct reference to the existing C code base.

* Define a visitor API for conversion of instance data structures to classes in other languages. These classes may or may not look anything like the original object-oriented models. Note that conversions of this sort to flat-file data storage formats (for reloading in ascend later) and to object-free (flat) modeling languages are in the ascend code base already.

See also: Persistence, Openoffice below.

Contact person: [[Ben Allan]]
Level of difficulty: medium
Language: C / ANTLR / ?
Priority: Medium

== Persistence of modelling results ==

Currently, ASCEND models are loaded and solved afresh each time. But sometimes, it can take a bit of fiddling to acheive solution of a model. In these cases, it would be useful to be able to save the model state and load it again into ASCEND. A coherent proposal for how to do this needs to be prepared, in discussion with the ASCEND team, by a student who would like to work in this area. Because this task involved loading and saving model state, it is proposed that it could also incorporate more general data export functionality, eg to export whole/partial model results to a CSV or tab-delimited file, for use with other tools. How this system would work with 'observers' and 'integrator' output is an open question. See also [[Saving and restoring model state]].

* Contact person: [[John Pye]]
* Level of difficulty: Low-medium
* Languages: C, Python, possibly some Tcl.
* Priority: Medium

== GAMS/AMPL interface ==

The optimisation programs GAMS and AMPL provide well-defined ('server') interfaces with which their solvers interact (as 'clients'). It should be possible for ASCEND to reproduce the GAMS and/or AMPL server interfaces, and hence to allow ASCEND immediate access to re-using all of the solvers implemented for those programs. The same could possibly also be said of the CUTEr solver/problem suite.

* Contact person: [[John Pye]]
* Level of difficulty: Medium
* Must know: numerical methods, operations research
* Languages: C
* Priority: Medium

== CMSlv with IPOPT, improvements to solver API ==

In GSOC2009, Mahesh completed the tie-in of the [[IPOPT]] solver into ASCEND. Next, we would like to modify our current CMSlv solver to be able to use IPOPT or CONOPT interchangeably, so that we have a completely open-source way of doing [[conditional modelling]]. An important part of this project would be reviewing of current solver APIs and making changes to allow solvers to work well in 'nested' ways, for example, for CMSlv to make calls to IPOPT. Down the track, we might also want other combinations, such as a dynamic optimiser, in which [[IPOPT]] makes calls to [[IDA]], for example.

* Contact person: [[John Pye]]
* Level of difficulty: medium
* Languages: C.
* Priority: Medium

== Export/Import ASCEND models to OpenOffice spreadsheet ==

We would like to be able to export models and data sets to spreadsheets,
as the spreadsheet is the most common interface used by energy systems modelers
today. Export will give advanced modelers using ascend more ways to communicate
their results to others. Import from spreadsheets and data exchange will give spreadsheet modelers
access to all ASCEND solvers without loss of their preferred user interface.

* Contact person: John Pye
* Level of difficulty: medium
* Languages: most likely C, python, XML.
* Priority: Low

== Parameter estimation ==

We would like to be able to process a dynamic ASCEND model with experimental data, and use the experimental data to give us estimates of the key operating parameters of the system. This would be useful for fitting models to experimental data in situations where simple steady-state measurements can not provide those parameters. It is anticipated that this would make use of similar code to the [[IPOPT]] solver, but would probably require a new Estimation API to be set up; defining a suitable API would be part of this project.

One application of this type of modelling would be to use inside and outside temperature measurements for a house, taken over a few days, to predict its thermal characteristics (insulation effectiveness, thermal mass, etc), as a simple way of evaluating whether a house meets current standards of energy efficiency.

* Contact person: John Pye
* Level of difficulty: medium
* Must know: numerical methods, modern control theory
* Languages: C
* Priority: Low (until someone has an itch!)

== Parallelising ASCEND computations ==

There is the potential for large speedups in ASCEND by implementing parallel evaluation of equation residuals. For systems with a large number of equations in a single block, this could give very large improvements. This project would involve writing a new [[Solvers|Solver]] based on [[QRSlv]] that incorporated message passing using [http://en.wikipedia.org/wiki/OpenMP OpenMP] or similar.
More detailed ideas on [[Parallelizing ASCEND]]. GSOC applicants interested in this area should consider working the [[OpenMP Exercise]] (our apologies to anyone who may have tried for 2010 the [[Differentiation Exercise]] that has expired.

* Contact person: Ben Allan
* Level of difficulty: medium-high
* Priority: Medium/Low
* Languages: C/C++ (with MPI, OpenMP, etc)

== [[Reaction kinetics data]] support ==

Currently, reaction rate models in ASCEND are done on an ad hoc basis. Assorted tools, notably [http://en.wikipedia.org/wiki/CHEMKIN CHEMKIN], define and support a widely used [http://www.frad.t.u-tokyo.ac.jp/public/chemkin/CKm_man.html.en text input format] for describing chemical reaction rate equations. This project would include:
* creating or adapting an open-source parser of the CHEMKIN data format to generate a data representation suitable for machine transformations.
* defining a transformation instance that maps the equations into ASCEND equation code.
* defining a transformation instance that maps the equations into python, C or C++ code for performance comparisons.
* demonstrating the use of the tool on test problems related to renewable energy systems: H<sub>2</sub>-air or methane-water.
* [https://github.com/OpenCFD/OpenFOAM-1.7.x/tree/master/src/thermophysicalModels/reactionThermo/chemistryReaders/chemkinReader this code] may be of some help, possibly.

* Contact person: Ben Allan, Krishnan Chittur
* Level of difficulty: low-medium
* Must know: physical chemistry, chemical engineering, numerical methods
* Languages: C (but other compiled languages may be possible)
* Priority: Low

== Thermophysical properties database ==

ASCEND includes a set of native ASCEND models that provide support for thermodynamic property correlations of a number of types. The current system is fully open and extensible, but its use of native ASCEND syntax makes it difficult to maintain, and difficult to browse the list of available chemical species. It also makes it difficult for users to work out how to add support for new substances. This project would involve migrating the chemical property data to a separate data file (perhaps via an [http://www.sqlite.org SQLite] and then implementing a suitable interface between ASCEND and that database so that chemical property formulations could be loaded from the database by a suitable statement in the ASCEND model file. A range of tests would need to be developed to prove that the property formulations worked as expected. It might be possible to investigate other freely-available sources of chemical property data, and import that data if suitable. In performing this work, it would be desirable to consider the edicts of the [http://co-lan.org CAPE-OPEN] project, which specifies a possible API for accessing chemical property data in a platform-agnostic way. Some partial efforts have been made to implement a suitable system, see [[FPROPS]], although currently this consists only of pure C code, with no mechanism for loading material properties from a database, and no support for mixtures of fluids.

* Contact person: [[Krishnan Chittur]]
* Level of difficulty: low-medium
* Must know: chemical engineering, physical chemistry
* Languages: C
* See also <a href="#FPROPS" title="">#FPROPS</a>
* Priority: Medium

== Packaging for Mac ==

ASCEND has now been [[Porting_to_Mac|ported to Mac OS X]]. What remains to be done, however, is to create an application bundle that runs in the way users expect. This project will require the user to create a suitable set of 'frameworks' and 'packages' that allow ASCEND to run in a Mac-ish way, but without too much disruption to the overall codebase. One key challenge is to provide suitable Apple Event bindings so that models can be opened using the ASCEND GUI.

This project seems as thought it may be a bit small so we'd be looking for a candidate who's already demonstrated their willingness to tackle a range of other tasks relating to the overall improvement of the program.

* Contact person: John Pye, Art Westerberg
* Level of difficulty: low-medium
* Priority: Medium
* Languages: C, Python, plus maybe some need for Apple-specific languages like Objective C.

== New Compiler ==

The ASCEND compiler is currently highly efficient, but it has a large and complicated body of code based around the Flex/Bison toolset. Using more modern compiler-generators such as ANTLR we believe it will be possible to rewrite the ASCEND compiler to be more modular, more maintainable and hopefully faster. This task would be very challenging and require fairly extensive experience with compiler-compilers and small-language implementation. More detailed ideas on a [[New Compiler]]

* Contact person: Ben Allan
* Level of difficulty: very high
* Languages: flexible, would need to interface with current instance hierarchy C code

== [[FPROPS]] ==

[[FPROPS]] is a module of code developed by John Pye to support thermodynamic property evaluations using Helmholtz correlation equations. This has the potential to be a very powerful and flexible solution to the problem of high-accuracy thermodynamic property evaluation, but it is still missing some crucial code relating to the location of the saturation line. A student with a strong understanding of thermodynamics would be able to complete this project. The real difficulty is in the thermo, the coding would be pretty straight-forward.

* Contact person: John Pye
* Level of difficulty: low (programming), medium (thermodynamics), medium (numerical methods)
* Languages: C, ASCEND.
* Priority: Medium

Current activity: [[User:Ankitml|Ankit Mittal]] from IIT Bombay is working on some aspects of this task, but more work is also required in other areas.

== Your Own Ideas ==

There are many other areas of possible work on ASCEND, including those from our long list of current and future [[Development Activities]]. Feel free to discuss other possible ideas with us, see [[Support]] for contact details.

* Contact person: send email to the 'users' mailing list (see [[Support]])

= Completed projects =

These are the summaries of the projects that were undertaken during [[:Category:GSOC2009|our participation]] in [http://socghop.appspot.com/org/home/google/gsoc2009/ascend GSOC 2009].

== [[Real-time ASCEND]] (more work is possible) ==

The core engine of ASCEND is a low-level C code compiler and set of solvers. It is conceivable that ASCEND could be incorporated into a real-time control and/or parameter estimate engine, using live data feeds for its modelling calculations. This is an open-ended project, with the hope that basic use of ASCEND for this application could be demonstrated. With such a capability it would be possible to contemplate using ASCEND to control systems that change over time, by allowing the values of system parameters to be adjusted in response to changing system behaviour.

* Contact person: John Pye
* Level of difficulty: medium
* Lanaguages: C

== [[Non-proprietary Optimisation]] (completed) ==

ASCEND is a free/open source software package licensed under the GPL. We have a number of [[Solvers]] in our software, including a wrapper for the excellent optimisation solver [[CONOPT]]. Unfortunately, however, this solver is expensive commercial software and can not be distributed freely as part of ASCEND. The lack of a good (free) optimisation solver limits the utility of ASCEND for many users.

This project would involve linking the [[IPOPT]] solver (or possibly some other suitable alternative, if any exists) to ASCEND, allowing us to run complex optimisation problems in ASCEND. Some work would be required to give ASCEND the ability to evaluate Hessian matrices (second derivatives of object functions), then tying it all together so that ASCEND can pass values and parameters etc through to the IPOPT solver.

Further work on this project could include development of a benchmarking suite using various standard sets of optimisation problems such as [http://hsl.rl.ac.uk/cuter-www/ CUTEr].

Note that there is a fairly new repository of open-source optimisation code now available from https://software.sandia.gov/trac/acro/wiki/Overview.

* Contact person: Ben Allan
* Level of difficulty: medium-high.
* Language(s): C

== Adding Exact Numerical Differentiation for Second Partial Derivatives (completed) ==

(combined with 'Non-proprietary Optimisation')

When solving nonlinear equations, the ASCEND solver creates exact numerical derivatives to create needed jacobian matrices. This task would be to extend these capabilities to generate exact numerical second derivatives, which could then support optimization solvers. The approach one can use is <a href="/images/c/c3/PhDthesisChungExactNumDiffChapt6.pdf" class="internal" title="PhDthesisChungExactNumDiffChapt6.pdf"> in Chapter 6 (596 kB pdf)</a> of Yonsoo Chung, <u>Solving Index and Near Index Problems in Dynamic Simulation</u>, PhD Thesis, Dept. of Chemical Engineering, Carnegie Mellon University (1991).

Please consider submitting a response to the [[Differentiation Exercise]] if applying for this topic under GSOC.

* Contact person: John Pye and Art Westerberg
* Level of difficulty: medium
* Languages: C

== Renewable energy system modelling (more work is possible) ==

ASCEND has all the built-in capabilities needed to solve systems of equations, and historically has been used to solve some difficult modelling problems in chemical and process engineering. We would like to improve its usefulness in the field of [[renewable energy systems modelling]], through the development of some reusable modelling 'blocks' for common system components. These would include flat-plate solar hot water collectors, [[Calculation_of_sun_position|sun position]], [[Data_reader|weather data]], photovoltaic panels, pumps, turbines, storage tanks, and so on. The goal would be to allow typical engineers to quickly produce accurate models of renewable energy systems for various locations, hopefully including prediction of their economic performance.

Much information on modelling these types of systems is available in books like Duffie and Beckman ([[Special:BookSources/0471698679|ISBN 0471698679]]), Flynne ([[Special:BookSources/0852964196|ISBN 0852964196]]) and elsewhere. This project would involve pulling together a coherent set of models for this task, and testing them carefully and making sure they are reusable and well-documented so that they can be of maximum use to the community.

* Contact person: John Pye
* Level of difficulty: low-medium
* Languages: ASCEND, possibly some C for 'hard to converge' models if necessary.

== Improved ODE/DAE support (completed) ==

ASCEND currently has a system for allowing users to model [[Dynamic_modelling|dynamic systems]]. You can specify variables that are the derivatives of other variables, and then use a special [[External_Integrators|Integrator]] to solve for time-varying behaviour of your model. We support a number of Integrators, including [[IDA]], [[LSODE]] and [[DOPRI5]].

Unfortunately, however, the ASCEND syntax for dynamic models is very clumsy, and this makes it hard to write compact, readable models for such systems.

This project would involve implementing proposed [[LINK semantics]] for ASCEND (in itself a value enhancement to the ASCEND language), then, upon that, building a new ODE/DAE syntax so that dynamic models could be succinctly expressed with the ASCEND modelling language. This would require you to become familiar with the [http://flex.sourceforge.net/ Flex] and [http://www.gnu.org/software/bison/ Bison] tools, which are used to implement the ASCEND language parser, so that you could then extend out language grammar with the necessary additional language constructs.

Further work on this project could include enhancing the reporting from [[External Integrators]] including perhaps a live graphical plot of progress or improvements to the [[Data reader]] to allow arbitrary input data to be fed into a simulation.

* Contact person: Ben Allan
* Level of difficulty: high
* Languages: C, Flex/Bison

== [[Canvas-based modeller for ASCEND]] (more work is possible) ==

Power stations are large and systems of many interacting components, including turbines, boilers, pumps and controllers. Their complexity arises as optimisations are applied, to extract the maximum possible energy from the available resource. The preferred way of modelling these systems is through the use of (very expensive) canvas-based GUI software in which 'blocks' are shown connected by lines, and parameters can be adjusted by editing the data behind the various blocks in the model. Some work has [[Canvas-based_modeller_for_ASCEND|already taken place]] within the ASCEND project to implement a GUI, using [http://gaphor.devjavu.com/wiki/Subprojects/Gaphas Gaphas], allowing these kinds of energy systems to be modelling using a GUI, but further work is required. It is anticipated that great progress could be made on this if someone were able to dedicate a few months to the job, and the result would be an open energy modelling system that would be much more user-friendly for those people who don't like writing text-based models.

* Contact person: John Pye
* Level of difficulty: low-medium
* Languages: Python (GTK, Cairo)

== [[Automatic recursive initialisation]] (completed by the ASCEND developers) ==

Extend ASCEND's [[METHODS]] code so that certain methods are run recursively one instantiated [[MODEL|MODELs]]. This would allow simpler code for setting initial values of solver variables, and make constructing robust models easier, especially in the context of canvas-based modelling tools. Making this stuff work is probably an prerequisite for an efficient [[canvas-based modeller for ASCEND]], because it allows 'blocks' to be initialised without the user having to explicitly request it.

* Contact person: [[John Pye]]
* Level of difficulty: Medium
* Languages: C
* Priority: Medium

== Embedded solver settings (completed by the ASCEND developers) ==

Difficult-to-solve models often require a bit of tweaking of the solver parameters, tolerances, etc, before a model will solve as intended. Currently, this must be done either manually via the GUI(s), or else through a script that exists separately from the model. We would like a way to embed solver parameter settings directly within the model. One approach that partly does the job (although not very nicely) is [[solver NOTES]]. We have also discussed the idea of a couple of new 'solver request' keywords, such as <tt>SET</tt> and <tt>SOLVER</tt> (see [[Controlling the solvers from within METHODS]]). This project would involve leading a design discussion to work out the best possible solution to this problem, and then implementing the agreed solution, as well as thorough testing.

* Contact person: [[John Pye]]
* Level of difficulty: medium
* Languages: C, Python, Tcl/Tk (if both GUIs are to be supported)
* Priority: Medium/High

== Prototype compiler ==

Building a whole new compiler implementation and hooking it to the existing C system is very difficult (very high quality code and testing required), and is generally unsuitable for a 3 month project. A solid contribution possible in 3 months, however, is to create the basis for a new parser infrastructure and ascend4 language migration tool. The particulars are open to negotiation, but may include development of parsers and walkers from scratch in ANTLR or the extension of an existing language (e.g. [http://chapel.cray.com/ Chapel]?) to support equation based programming. See also chapel.cray.com and elsewhere in this site for Ben's scribblings on new compiler design.

* Contact person: [[Ben Allan]]
* Level of difficulty: Low-Medium
* Priority: Medium
* Must know: ANTLR or other compiler development tools
* Languages: ASCEND, probably java, optionally C, Fortran

[[Category:Development]]