Merge pull request #21 from easifem/vikas-dev

Vikas dev

Author: vickysharma0812

docs/docs-api/FEDOF/Copy.md

@@ -0,0 +1,67 @@
+# Copy
+
+The `Copy` method copies the contents of one `FEDOF_` object to another. This method is also used by the assignment operator (`=`) for `FEDOF_` objects.
+
+## Interface
+
+```fortran
+INTERFACE
+  MODULE SUBROUTINE Copy(obj, obj2)
+    CLASS(FEDOF_), INTENT(INOUT) :: obj
+    CLASS(FEDOF_), INTENT(IN) :: obj2
+  END SUBROUTINE Copy
+END INTERFACE
+```
+
+## Parameters
+
+- `obj` - The destination `FEDOF_` object that will receive the copied data
+- `obj2` - The source `FEDOF_` object whose data will be copied
+
+## Implementation Details
+
+The method performs a shallow copy of most attributes from `obj2` to `obj`:
+
+1. Copies basic properties:
+   - `isLagrange` - Flag indicating if the base interpolation is Lagrange
+   - `tdof` - Total number of degrees of freedom
+   - `tNodes`, `tEdges`, `tFaces`, `tCells` - Total count of different mesh entities
+   - `baseContinuity` - Continuity or conformity of basis (e.g., "H1")
+   - `baseInterpolation` - Type of basis functions (e.g., "LAGR", "HIER")
+   - `maxCellOrder`, `maxFaceOrder`, `maxEdgeOrder` - Maximum order values
+
+2. Sets the mesh pointer to point to the same mesh as the source object:
+
+```fortran
+obj%mesh => obj2%mesh
+```
+
+3. Copies array data when allocated in the source object:
+   - `cellOrder` - Order of each cell
+   - `faceOrder` - Order of each face
+   - `edgeOrder` - Order of each edge
+   - `edgeIA`, `faceIA`, `cellIA` - Sparsity patterns for different entities
+
+4. Associates finite element pointers:
+
+```fortran
+DO ii = 1, SIZE(obj2%fe)
+  isok = ASSOCIATED(obj2%fe(ii)%ptr)
+  IF (isok) THEN
+    obj%fe(ii)%ptr => obj2%fe(ii)%ptr
+  END IF
+END DO
+```
+
+## Notes
+
+- This is a shallow copy - the mesh and finite element pointers in the destination object point to the same objects as the source.
+- Array data is copied only if it exists in the source object.
+- The method doesn't allocate new memory for arrays; it assumes the destination arrays either don't exist or are already properly allocated.
+- This method is particularly useful when you need to create a duplicate of a `FEDOF_` object without creating new underlying mesh or finite element instances.
+
+## Example
+
+import EXAMPLE65 from "./examples/_Copy_test_1.md";
+
+<EXAMPLE65 />

docs/docs-api/FEDOF/Deallocate.md

@@ -0,0 +1,41 @@
+# Deallocate
+
+The `Deallocate` method releases all allocated memory and nullifies pointers in a `FEDOF_` object, returning it to an uninitialized state. This method is essential for proper memory management to prevent memory leaks.
+
+## Interface
+
+```fortran
+INTERFACE
+  MODULE SUBROUTINE DEALLOCATE (obj)
+    CLASS(FEDOF_), INTENT(INOUT) :: obj
+  END SUBROUTINE DEALLOCATE
+END INTERFACE
+```
+
+## Parameters
+
+- `obj` - The `FEDOF_` object to be deallocated
+
+## Notes
+
+- This method checks if arrays are allocated before attempting to deallocate them, preventing potential runtime errors.
+- For each associated finite element pointer, it calls the `DEALLOCATE` method of the finite element object before nullifying the pointer.
+- The method does not deallocate the mesh itself, as the `FEDOF_` object only maintains a pointer to the mesh, which might be used elsewhere.
+- After calling this method, the `FEDOF_` object is reset to its default state and can be reused for a new initialization.
+
+## Example Usage
+
+```fortran
+TYPE(FEDOF_) :: dof
+
+! After using dof...
+CALL dof%DEALLOCATE()
+
+! Now dof can be reused or safely go out of scope
+```
+
+## Important Considerations
+
+- This method should be called when the `FEDOF_` object is no longer needed to prevent memory leaks.
+- It's particularly important to call this method before reinitializing an existing `FEDOF_` object to avoid memory leaks.
+- The method only deallocates resources directly owned by the `FEDOF_` object; it does not deallocate the mesh or other external resources that might be referenced by pointers.

docs/docs-api/FEDOF/GetBaseInterpolation.md

@@ -0,0 +1,80 @@
+# GetBaseInterpolation
+
+The `GetBaseInterpolation` method returns the type of basis functions used for interpolation on the reference element in the FEDOF (Finite Element Degrees of Freedom) instance. 
+
+## Interface
+
+The specific interface is defined as:
+
+```fortran
+MODULE FUNCTION obj_GetBaseInterpolation(obj) RESULT(ans)
+  CLASS(FEDOF_), INTENT(IN) :: obj
+  CHARACTER(:), ALLOCATABLE :: ans
+END FUNCTION obj_GetBaseInterpolation
+```
+
+## Description
+
+The `GetBaseInterpolation` method returns the type of basis functions used for interpolation on the reference element in the FEDOF (Finite Element Degrees of Freedom) instance. This information is crucial for understanding how the finite element approximation is constructed.
+
+### Parameters
+
+- `obj` - Input, `CLASS(FEDOF_)`, FEDOF object instance
+- `ans` - Output, `CHARACTER(:), ALLOCATABLE`, string containing the base interpolation type
+
+### Implementation Details
+
+The implementation is straightforward, returning the internal `baseInterpolation` property:
+
+```fortran
+MODULE PROCEDURE obj_GetBaseInterpolation
+ans = obj%baseInterpolation
+END PROCEDURE obj_GetBaseInterpolation
+```
+
+### Possible Return Values
+
+The method returns one of the following interpolation types:
+
+- `"LAGR"` - Lagrange interpolation
+- `"HIER"` - Hierarchical interpolation
+- `"ORTHO"` - Orthogonal interpolation
+- `"HERM"` - Hermite interpolation
+- `"SERE"` - Serendipity interpolation
+
+## Usage Example
+
+```fortran
+! Example to get the base interpolation type
+CHARACTER(:), ALLOCATABLE :: interpType
+TYPE(FEDOF_) :: myDOF
+
+! Get the interpolation type
+interpType = myDOF%GetBaseInterpolation()
+
+! Check interpolation type and take appropriate action
+SELECT CASE (interpType)
+CASE ("LAGR")
+  PRINT *, "Using Lagrange interpolation"
+CASE ("HIER")
+  PRINT *, "Using Hierarchical interpolation"
+CASE DEFAULT
+  PRINT *, "Using other interpolation type: ", interpType
+END SELECT
+```
+
+## Important Notes
+
+1. The base interpolation type works in conjunction with the base continuity (e.g., "H1", "HCurl", "HDiv", "DG") to determine the complete function space used.
+2. The `GetCaseName` method combines the base continuity and base interpolation into a single identifier (e.g., "H1LAGR").
+3. Different interpolation types have different mathematical properties and are suitable for different types of problems.
+
+## Related Methods
+
+- `GetCaseName` - Returns the combined continuity and interpolation identifier
+- `GetLocalElemShapeData` - Uses the interpolation type to determine which shape functions to compute
+- `GetLocalElemShapeDataH1Lagrange` - Specialized method for Lagrange interpolation
+- `GetLocalElemShapeDataH1Hierarchical` - Specialized method for Hierarchical interpolation
+
+The `GetBaseInterpolation` method is important for understanding the mathematical basis of the finite element approximation and is often used to determine which specialized algorithms should be applied for shape function evaluation and element matrix assembly.
+

docs/docs-api/FEDOF/GetCaseName.md

@@ -0,0 +1,81 @@
+# GetCaseName
+
+The `GetCaseName` method returns a string that identifies the combination of continuity and interpolation type used in the finite element degree of freedom object. This case name is used internally to determine which algorithms to apply when processing the finite element data.
+
+## Interface
+
+```fortran
+INTERFACE
+  MODULE FUNCTION GetCaseName(obj) RESULT(ans)
+    CLASS(FEDOF_), INTENT(IN) :: obj
+    CHARACTER(6) :: ans
+  END FUNCTION GetCaseName
+END INTERFACE
+```
+
+## Parameters
+
+- `obj` - The `FEDOF_` object from which to obtain the case name
+
+## Return Value
+
+- `ans` - A 6-character string combining the basis continuity and the interpolation type
+
+## Implementation Details
+
+The method is straightforward, concatenating the `baseContinuity` and `baseInterpolation` properties of the `FEDOF_` object:
+
+```fortran
+ans = obj%baseContinuity//obj%baseInterpolation
+```
+
+## Possible Return Values
+
+The return value is a combination of the continuity type and interpolation type:
+
+1. For continuity (`obj%baseContinuity`):
+   - `"H1"` - Standard $H^{1}$ conforming elements
+   - `"HC[url]"` - H(curl) conforming elements
+   - `"HD[iv]"` - H(div) conforming elements
+   - `"DG"` - Discontinuous Galerkin elements
+
+2. For interpolation (`obj%baseInterpolation`):
+   - `"LAGR"` - Lagrange interpolation
+   - `"HIER"` - Hierarchical interpolation
+   - `"ORTHO"` - Orthogonal interpolation
+   - `"HERM"` - Hermite interpolation
+   - `"SERE"` - Serendipity interpolation
+
+Common combinations include:
+
+- `"H1LAGR"` - H¹ conforming elements with Lagrange interpolation
+- `"H1HIER"` - H¹ conforming elements with hierarchical interpolation
+- `"DGHIER"` - Discontinuous Galerkin with hierarchical interpolation
+
+## Usage Examples
+
+The case name is primarily used in conditional branching to select the appropriate algorithms for a given finite element type:
+
+```fortran
+CHARACTER(6) :: casename
+casename = fedof%GetCaseName()
+
+SELECT CASE (casename)
+CASE ('H1LAGR')
+  ! Process H¹ conforming elements with Lagrange interpolation
+CASE ('H1HIER')
+  ! Process H¹ conforming elements with hierarchical interpolation
+CASE ('DGHIER')
+  ! Process Discontinuous Galerkin with hierarchical interpolation
+CASE DEFAULT
+  ! Handle unexpected case
+END SELECT
+```
+
+This method is used extensively within the `FEDOF_` class to determine the appropriate algorithms for shape function calculation, connectivity generation, and other operations that depend on the specific type of finite element formulation.
+
+## Example
+
+import EXAMPLE80 from "./examples/_GetCaseName_test_1.md";
+
+<EXAMPLE80 />

docs/docs-api/FEDOF/GetCellDOF.md

@@ -0,0 +1,57 @@
+# GetCellDOF
+
+Get the degrees of freedom associated with a specific cell (element volume) in the finite element mesh.
+
+## Interface
+
+```fortran
+MODULE SUBROUTINE GetCellDOF(obj, globalCell, ans, tsize, islocal)
+  CLASS(FEDOF_), INTENT(IN) :: obj
+  INTEGER(I4B), INTENT(IN) :: globalCell
+  INTEGER(I4B), INTENT(INOUT) :: ans(:)
+  INTEGER(I4B), INTENT(OUT) :: tsize
+  LOGICAL(LGT), INTENT(IN), OPTIONAL :: islocal
+END SUBROUTINE GetCellDOF
+```
+
+## Parameters
+
+- `obj`: The FEDOF_ object
+- `globalCell`: Global cell number to retrieve DOFs for
+- `ans`: Integer array to store the retrieved DOFs
+- `tsize`: Output parameter containing the total size of data written in ans
+- `islocal`: Optional logical flag - if true, globalCell is treated as a local cell number
+
+## Functionality
+
+This method retrieves all degrees of freedom associated with a specific cell (element volume) identified by its global cell number. It performs the following operations:
+
+1. Converts the global cell number to a local cell number if needed
+2. Accesses the cell DOF information using the cell index array (`cellIA`)
+3. Populates the `ans` array with the DOF indices for the specified cell
+4. Sets `tsize` to the number of DOFs associated with the cell
+
+The implementation leverages the cell sparsity pattern stored in the `cellIA` array, which provides the start and end indices for each cell's DOF information.
+
+## Implementation Details
+
+The method first converts the global cell number to a local cell number using the mesh's `GetLocalElemNumber` method. It then iterates through the DOF indices stored for this cell, copying each one into the `ans` array and incrementing the `tsize` counter.
+
+## Usage
+
+The `GetCellDOF` method is important for finite element implementations where you need to:
+
+- Assemble matrices based on cell (volume) contributions
+- Apply internal conditions on specific cells
+- Compute cell-based integrals or other operations
+- Access all degrees of freedom associated with a cell for post-processing
+
+Unlike vertex, edge, or face DOFs which are typically shared between elements, cell DOFs are internal to a specific element, making them important for capturing high-order behavior within elements.
+
+## Example 1
+
+import CodeBlock from '@theme/CodeBlock';
+
+import CodeSnippet from '!!raw-loader!./examples/_GetCellDOF_test_1.md';
+
+<CodeBlock language="fortran">{CodeSnippet}</CodeBlock>