diff --git a/README.md b/README.md index a0573de..4fda2b4 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,29 @@ -![ForSolver](media/logo.png) -============ +[![GitHub](https://img.shields.io/badge/GitHub-ForSolver-blue.svg?style=social&logo=github)](https://github.com/gha3mi/forsolver) +[![Version](https://img.shields.io/github/release/gha3mi/forsolver.svg)](https://github.com/gha3mi/forsolver/releases/latest) +[![Documentation](https://img.shields.io/badge/ford-Documentation%20-blueviolet.svg)](https://gha3mi.github.io/forsolver/) +[![License](https://img.shields.io/github/license/gha3mi/forsolver?color=green)](https://github.com/gha3mi/forsolver/blob/main/LICENSE) +[![Build](https://github.com/gha3mi/forsolver/actions/workflows/CI_test.yml/badge.svg)](https://github.com/gha3mi/forsolver/actions/workflows/CI_test.yml) -**ForSolver**: A Fortran library of linear and nonlinear solvers. ------ - -## Table of Contents -- [](#) - - [Table of Contents](#table-of-contents) - - [Installation](#installation) - - [fpm](#fpm) - - [Linear system solver](#linear-system-solver) - - [Nonlinear system solver](#nonlinear-system-solver) - - [Tests](#tests) - - [Examples](#examples) - - [Example 1: Linear System Solver](#example-1-linear-system-solver) - - [Example 2: Newton's Method for Root Finding](#example-2-newtons-method-for-root-finding) - - [Documentation](#documentation) - - [Contributing](#contributing) ------ - -## Installation - -### fpm -ForSolver can be cloned and then built using [fpm](https://github.com/fortran-lang/fpm), following the instructions provided in the documentation available on Fortran Package Manager. - -```bash -git clone https://github.com/gha3mi/forsolver.git -cd forsolver -fpm install --prefix . -``` +**ForSolver**: A Fortran library of linear and nonlinear solvers. -Or you can easily include this package as a dependency in your `fpm.toml` file. +## Usage -```toml -[dependencies] -forsolver = {git="https://github.com/gha3mi/forsolver.git"} -``` ------ +### Linear system solver -## Linear system solver ```fortran use forsolver, only: solve + x = solve(A,b,method) ``` + available methods (optional): + - ```gesv``` - ```gels``` ------ -## Nonlinear system solver +### Nonlinear system solver + ```fortran use forsolver, only: nlsolver @@ -66,7 +40,9 @@ call nls%set_options(& call nls%solve(F, dFdx, x0, x_sol) ``` + available nl_methods: + - ```newton``` - ```newton-modified``` - ```newton-quasi-fd``` @@ -78,42 +54,41 @@ fd: finite difference method cs: complex step method ------ +## Requirements -## Tests +- A Fortran Compiler +- BLAS Library +- Fortran Package Manager (fpm) -The `tests` directory contains test programs to verify the functionality of the `forsolver` module. To run the tests using `fpm`: +## fpm Dependency -- For Intel Fortran Compiler (ifort): -```bash -fpm @ifort -``` +If you want to use `ForSolver` as a dependency in your own fpm project, +you can easily include it by adding the following line to your `fpm.toml` file: -- For Intel Fortran Compiler (ifx): -```bash -fpm @ifx +```toml +[dependencies] +forsolver = {git="https://github.com/gha3mi/forsolver.git"} ``` -- For NVIDIA Compiler (nvfortran): -```bash -fpm @nvidia -``` +## Runing Tests + +Execute the following commands to run tests with specific compilers: -- For GNU Fortran Compiler (gfortran): -```bash -fpm @gfortran +```shell +fpm @-test ``` ------ +`compiler: ifx, ifort, gfortran, nvfortran` + ## Examples ### Example 1: Linear System Solver ```fortran -program test1 +program example1 use kinds - use forsolver, only: solve + use forsolver implicit none @@ -121,68 +96,75 @@ program test1 real(rk), dimension(:) , allocatable :: x, b integer :: m,n, i, j - m = 4 - n = 3 + m = 3 + n = 2 allocate(A(m,n),b(m),x(n)) - call random_number(A) - call random_number(b) - A = A*10.0_rk - b = b*10.0_rk - - X = solve(A, b) - - ! Print A - print *, "A:" - print "(4F10.6)", (A(:,j), j = 1, m) + A(1,:) = [ 1.0_rk, 5.0_rk] + A(2,:) = [ 3.0_rk, 1.0_rk] + A(3,:) = [-2.0_rk, 4.0_rk] - ! Print b - print *, "b:" - print "(4F10.6)", b + b = [4.0_rk, -2.0_rk, 3.0_rk] + x = solve(A, b) - ! Print x - print *, "x:" - print "(4F10.6)", x - - deallocate(A,b,x) - -end program test1 +end program example1 ``` ### Example 2: Newton's Method for Root Finding ```fortran -program test3 - +module my_function3 use kinds - use functions_module - use forsolver, only: nlsolver + implicit none +contains + function F1(x) result(F_val) + real(rk), intent(in) :: x + real(rk) :: F_val + F_val = 5.0_rk * x**3 + 8.0_rk * x - 5.0_rk + end function F1 + function dF1dx(x) result(dFdx_val) + real(rk), intent(in) :: x + real(rk) :: dFdx_val + dFdx_val = 15.0_rk * x**2 + 8.0_rk + end function dF1dx +end module my_function3 + +program example2 + + use forsolver + use my_function3 implicit none type(nlsolver) :: nls - real(rk) :: x_sol + real(rk) :: x, expected_x call nls%set_options(& nl_method = 'newton',& maxit = 100,& - TolFun = 1e-15_rk,& + TolFun = 1e-4_rk,& verbosity = 1) - call nls%solve(F=F1, dFdx=dF1dx, x0=10.0_rk, x_sol=x_sol) + call nls%solve(F=F1, dFdx=dF1dx, x0=10.0_rk, x_sol=x) -end program test3 +end program example2 ``` ------ -## Documentation -To generate the documentation for the `ForSolver` module using [ford](https://github.com/Fortran-FOSS-Programmers/ford) run the following command: -```bash +## API Documentation + +The most up-to-date API documentation for the master branch is available +[here](https://gha3mi.github.io/ForSolver/). +To generate the API documentation for `ForSolver` using +[ford](https://github.com/Fortran-FOSS-Programmers/ford) run the following +command: + +```shell ford ford.yml ``` ------ ## Contributing -Contributions to `ForSolver` are welcome! If you find any issues or would like to suggest improvements, please open an issue or submit a pull request. \ No newline at end of file + +Contributions to `ForSolver` are welcome! +If you find any issues or would like to suggest improvements, please open an issue. \ No newline at end of file