CellCompiler Files

CellCompiler latest version: 0.2


************************************** Installation Instructions ********************************

The current version of the CellCompiler can be used to generate simulation code for biological function
model simulations in two-dimensional meshes. To run the program, please follow the following steps:

1. Download the latest version of the CellCompiler in the Files section of the CellMLCompiler Sourceforge page and then 
    go to CellMLCompiler -> Source Code -> <latest_version>.zip (latest file is CellCompiler 0.2.zip).

2. After downloading the source code, unzip it in your local directory.

3. To open the project:
   
   In Eclipse (Eclipse Java SDK 4.2): 
       	3.1. Go to File -> Import... -> General -> Existing Projects into Workspace
	3.2. In the 'Select root directory' field, browse in the directory where you unzipped the source code. 
                The name of the latest version of CellCompiler project should appear under the 'Projects' check list.
  	3.3. Check the box indicating the latest version and click 'Finish'.

4. To run the code generator:
    
   In Eclipse (Eclipse Java SDK 4.2): 
	4.1. Go to Run -> Run Configurations.... A pop-up window will appear where you need to put the run arguments.
	4.2. In the 'Name' field of the 'Run Configurations' window, supply the name of the main class, which is 
	        CellCompilerMain.
	4.3. In the arguments tab under the 'Name' field, put the run arguments for the code that you want to generate.
		A sample run argument is:
	
		-C RelMLPDE ./model/RelMLPDE/FHN_FTCS_Diffusion_2DV5_5x5.relml ./output fhn_ftcs_5x5
	
		-C 		= generate C code
		RelMLPDE	= use the RelMLPDE parser
		./model/...	= directory of the input RelML file
		./output 	= directory where you want to save the generated code (should should be created first)
		fhn_ftcs_...	= file name you want to assign to the generated code
	
	4.4. Press 'Run' to run the code generator and create the program code.
	4.5. The generated code should appear in the output directory specified in the run arguments. For the
		C program generator, one source file should be created if you use explicit FDM schemes like FTCS, 
		while two source files plus a header file should be created if you use implicit schemes like 
		Crank-Nicolson method. The extra source and header files are for the Newton solver for implicit methods.

5. To run the generated code, compile it in any general-purpose compiler. 
	

************************************** Input files ********************************

(1) RELML:

The main input that you need in order to generate a program code is the RelML file. This file contains the name of the
   biological function model and PDE numerical scheme that you want to use. Part of the RelML file for PDE looks like the
   following:

------------------------------ Start of file -----------------------------

<!-- 		FHN_FTCS_Diffusion_2D_v5.relml	 			-->
<!-- Finite Difference solution in 2D for the FitzHugh-Nagumo model 	-->
<!-- with diffusion PDE and Forward-Time Central Space Scheme (FTCS)	-->

<relml>
	<cellml name="cellml0" filename="model/CellML/fhn_diffusion_2D.cellml"/>
	<tecml name="tecml0" filename="model/TecMLPDE/FTCS_Diffusion_2D_v5.tecml" />
	
	<tecmlvariable name="t">
 		<correspondcellml file="cellml0" component="Main" name="time" init="0"/>
	</tecmlvariable>
	<tecmlvariable name="x1">
 		<correspondcellml file="cellml0" component="Main" name="x1" />
	</tecmlvariable>
	.
	.
	.

</relml>

------------------------------ End of file -----------------------------

The name of the CellML file and its directory is supplied in the 'name' attribute of the <cellml> element and the name and    directory of the FDM numerical solution method is in the 'name' attribute of the <tecml> element. The variables in the
   CellML model are then sorted according to the different variables types indicated in the TecML file. In the example
   above, the 'time' variable in the 'Main' component of the FHN cellml file is sorted into the TecML variable 't'.

The listing and sorting of the variables in the RelML file is time-consuming and prone to errors if done manually, thus,
   we are creating a RelML file creator GUI to partially automate this step. The RelML generator should come together with
   the next version of CellCompiler.


(2) CELLML

The CellML files can be downloaded from the CellML repository in https://models.physiomeproject.org/cellml. For generating
   codes for simulations with only ODE, CellML files from the repository can be used as is. However, you need to insert 
   the necessary PDE part (e.g. diffusion term) in MathML format if you want to simulate in 1D, 2D or 3D. You can use
   tools like  MathML Weaver to create the PDE term in MathML format.


(3) TECML

The TecML files are already included in the source code folder. These are included under ./model folder in the main 
   project directory. For generating simulations with PDEs, the FDM numerical methods that you can use are in the
   ./model/TecMLPDE folder.