------------------
The Mka3D README
------------------

Contributor: Laurent Monasse, 03/02/2017

--------------------------------
Index
1. Introduction
2. How to compile the code
3. How to change parameters
4. How to visualize results
--------------------------------

------------------
1. Introduction
------------------

This simulation code is designed for those who wish to simulate continuum
mechanics using a Discrete Element Method. At the moment, the only behavior
law encoded is linear elasticity.

----------------------------
2. How to compile the code
----------------------------

A simple Cartesian mesh generator is provided. In order to compile the mesh
generator, type:
    make mesh
and run the mesh generator using:
    ./mesh
This generates the file "maillage.dat" which is used by the code.

You can then compile the main code using the command line:
    make
and run the code using the command line:
    ./Mka3d

You can make a clean-up of the compilation with the command:
    make clean

-----------------------------
3. How to change parameters 
-----------------------------

The tunable parameters are contained in three files: "param.dat", "vitesse.cpp" and "forces_ext.cpp".

The file "param.dat" gives a number of numerical and physical parameters used in the simulation. If these parameters are changed, you might need to regenerate the mesh. The main code will not need recompiling. The parameters are described briefly as follows.

RECOVERY 	     This tells the code whether the simulation should be
		     started from scratch (value 0) or should be restarted
		     from a previous recovery point (value 1)

NUM_RECOVERY	     In the event of a restart (RECOVERY=1), this value
		     indicates the number of the output file from which to
		     restart. The file "resultats/solideNUM.vtk" should exist.
		     The value has no effect when RECOVERY=0.

N_DIM		     Dimension of the problem. Should be 3 !

FLAG_2D		     0 if the problem is 3D, 1 if it is 2D

DENSITY		     Density of the solid material

POISSON_RATIO	     Poisson's ratio of the material ; the value should be <0.5
		     and >-1

YOUNG_MODULUS	     Young's modulus of the material

SIMULATION_TIME	     Total simulation time

CFL		     Courant-Friedrichs-Lewy condition number ; should be less
		     than 1. In practice, 0.5 is a reasonable value.

N_PRINTS	     Number of outputs (regularly spaced during the simulation
		     time) of the solid state.

MAX_STEPS	     Maximal number of steps in time during the simulation.
		     Does not affect the simulation time if chosen sufficiently
		     large. It is only a way to prevent abnormally large number
		     of iterations.

RECONSTRUCTION	     The Discrete Element Method Mka3d discretizes the solid
		     with rigid particles linked by cohesive forces. If
		     RECONSTRUCTION=0, the output gives the particles "as is"
		     with possible gaps and overlapping (unphysical). If
		     RECONSTRUCTION=1, a reconstruction of a continuous
		     interface is performed around the particle assembly. It
		     does not affect the simulation, only the output.

L_X,L_Y,L_Z	     Length of the solid in the x, y and z directions

N_X,N_Y,N_Z	     Number of discretization steps in the x, y and z directions

BOUNDARY_CONDITION_X Sets the boundary conditions in the x, y and z directions.
BOUNDARY_CONDITION_Y The two numbers denote the boundary conditions on the face
BOUNDARY_CONDITION_Z at x_min and x_max (resp. y_min and y_max, z_min and z_max)
		     The number 0 indicates that the boundary is free to move
		     (and might be subjected to external forces), while the
		     number 1 denotes the fact that the solid is clamped.

The file "vitesse.cpp" includes the functions "Vector_3 velocity(const Point_3 
&p)" and "Vector_3 omega(const Point_3 &p)".

velocity 	   returns the initial velocity prescribed for the solid at
		   point p.

omega 		   returns the initial angular velocity vector prescribed for
		   the solid at point p. 

The file "forces_ext.cpp" includes the functions "Vector_3 
Forces_externes(Point_3 X, Vector_3 e)" and "Vector_3 Moments_externes(Point_3
X, Vector_3 e)".

Forces_externes		returns the forces exerted on a	particle at position X
			and with rotation vector e (the vector aligned with the
			axis of rotation, such that the rotation is direct with
			regards to the direction of e and with norm
			|e|=sin(theta) with theta the angle of rotation).

Moments_externes	returns the moments exerted on a particle at position X
			and with rotation vector e.

-------------------------------
4. How to visualize results 
-------------------------------

The output are stored in the file "resultats".

The solid position is output at a number of times in files
"solide*.vtk". These files can be visualized with Paraview.

The energy variation is stored in the file "energie.dat". It can be
visualized with gnuplot using the command:
	   p "energie.dat" u 1:3 w l