The IMPORT statement in ASCEND model files is used to load external code that gives ASCEND new functionality. This includes loading external methods, external relations and external solvers (including Integrators), and even external import handlers, which allows you to provide the means to hook up new languages for the provision of any of these services.
For examples of what can be done with the IMPORT statement, see External Libraries.
See also REQUIRE, which is used to import other ASCEND models (as opposed to external non-ASCEND code).
What happens inside IMPORT
- First, valid importable files are looked for in the path specified in the ASCENDSOLVERS environment variable. If found, the importable file is loaded and the status of the load attempt is returned to the user.
- Second, valid importable files are looked for in the path specified in the ASCENDLIBRARY environment variable.
'Importable files' are those with filenames that match the patterns specified by available Import Handlers. Import handlers allows files like 'ascend_solver1.dll' (Windows) or 'ascend_solver1.so' (Linux) to be loaded using the statement 'IMPORT "solver1"', or alternatively you can load the Python code 'solver2.py' using the statement 'IMPORT "solver2"' (but read about ExtPy to understand more about this option). The current import handlers provided are 'extlib' for loading shared libaries (.so or .dll files), and ExtPy for loading external python scripts. ExtPy at present can only be used to provide External Methods functionality.
This allows your model file to be cross-platform as well as agnostic about the way that external functionality is defined. If it is defined as 'mystuff.py' or as 'ascend_mystuff.so', you still use the same 'IMPORT "mystuff"' statement. We wanted to hide the implementation details from the modeller, which is why the file extensions are left off.
See Environment variables for ASCEND for more information.
Default values for ASCENDSOLVERS and ASCENDLIBRARY
These variables are optional. If not specified in your environment, default values are used.
Also the possibility of using the .ascend.ini file. Need to check/document this.
Process, in more detail
Whenever ASCEND sees an IMPORT statement it uses an Import Handler to process it. ASCEND keeps a list of Import Handlers, and the first one that finds something it can import is given the job.
The process used is like this:
- ASCEND finds a statement like IMPORT "mything"
- It looks at the first Import Handler on its list
- It requests the Import Handler to translate the string mything into a filename corresponding to that particular handler
- ASCEND looks to see if the named file exists anywhere in the ASCENDLIBRARY path
- It moves through the list of Import Handlers until a file is found in the search path that matches the filename returned by the Import Handler
- ASCEND then calls the 'import' function for that particular Import Handler, passing it the full pathname of the file to be imported.
- The 'import' function can do whatever it likes. It could load a new solver, add external methods or blackbox functions, launch another program, etc. Any functionality exposed via the libascend.so API is accessible.
By default, there is only one Import Handler defined, called ExtFn. This import handler provides the ability to import external shared libraries. It handles the platform-specific naming conventions and the dlopen calls. You can use the ExtFn import handler to load other import handler for your specific task.
See also ExtPy which is an import handler for python scripts.