Add all documentation files
- SHA
a9a7856383a5b46ae172e490d376bfbf1c8f5591- Parents
-
6379d17 - Tree
42f238f
fortrangoingonforty/fortbite
/
a9a7856
Browse files
3 changed files
| Status | File | + | - |
|---|---|---|---|
| A |
DEVELOPER_GUIDE.md
|
338 | 0 |
| A |
QUICK_REFERENCE.md
|
133 | 0 |
| A |
USAGE_GUIDE.md
|
489 | 0 |
DEVELOPER_GUIDE.mdadded@@ -0,0 +1,338 @@ | |||
| 1 | +# FORTBITE Developer Guide | ||
| 2 | + | ||
| 3 | +This guide is for developers who want to understand, modify, or extend FORTBITE's codebase. | ||
| 4 | + | ||
| 5 | +## Architecture Overview | ||
| 6 | + | ||
| 7 | +FORTBITE follows a modular, layered architecture with clear separation of concerns: | ||
| 8 | + | ||
| 9 | +``` | ||
| 10 | +┌─────────────────────────────────────┐ | ||
| 11 | +│ User Interface │ | ||
| 12 | +│ (fortbite_io_m) │ | ||
| 13 | +├─────────────────────────────────────┤ | ||
| 14 | +│ Evaluator │ | ||
| 15 | +│ (fortbite_evaluator_m) │ | ||
| 16 | +├─────────────────────────────────────┤ | ||
| 17 | +│ Parser │ Functions │ | ||
| 18 | +│ (fortbite_parser_m)│(fortbite_funcs_m)│ | ||
| 19 | +├─────────────────────┼─────────────────┤ | ||
| 20 | +│ AST │ Arithmetic │ | ||
| 21 | +│ (fortbite_ast_m) │(fortbite_arith_m)│ | ||
| 22 | +├─────────────────────┼─────────────────┤ | ||
| 23 | +│ Lexer │ Matrix │ | ||
| 24 | +│ (fortbite_lexer_m) │(fortbite_matrix_m)│ | ||
| 25 | +├─────────────────────────────────────┤ | ||
| 26 | +│ Core Types │ | ||
| 27 | +│ (fortbite_types_m) │ | ||
| 28 | +├─────────────────────────────────────┤ | ||
| 29 | +│ Precision │ | ||
| 30 | +│ (fortbite_precision_m) │ | ||
| 31 | +└─────────────────────────────────────┘ | ||
| 32 | +``` | ||
| 33 | + | ||
| 34 | +## Module Reference | ||
| 35 | + | ||
| 36 | +### Core Modules | ||
| 37 | + | ||
| 38 | +#### `fortbite_precision_m.f90` | ||
| 39 | +**Purpose:** Defines precision parameters and floating-point kinds | ||
| 40 | +```fortran | ||
| 41 | +integer, parameter :: sp = real32 ! Single precision | ||
| 42 | +integer, parameter :: dp = real64 ! Double precision | ||
| 43 | +integer, parameter :: qp = real128 ! Quad precision (if available) | ||
| 44 | +``` | ||
| 45 | + | ||
| 46 | +#### `fortbite_types_m.f90` | ||
| 47 | +**Purpose:** Core data types and error handling | ||
| 48 | +```fortran | ||
| 49 | +type :: value_t ! Universal value container | ||
| 50 | +type :: variable_t ! Variable storage with linked list | ||
| 51 | +type :: token_t ! Lexical tokens | ||
| 52 | +type :: fortbite_error_t ! Unified error handling | ||
| 53 | +``` | ||
| 54 | + | ||
| 55 | +**Key functions:** | ||
| 56 | +- Matrix creation: `create_zeros_matrix()`, `create_ones_matrix()`, `create_eye_matrix()` | ||
| 57 | +- Value operations: `create_scalar()`, `create_complex()`, `destroy_value()` | ||
| 58 | +- Error handling: `set_fortbite_error()`, `create_error_value()` | ||
| 59 | + | ||
| 60 | +### Parsing Pipeline | ||
| 61 | + | ||
| 62 | +#### `fortbite_lexer_m.f90` | ||
| 63 | +**Purpose:** Tokenizes input strings into mathematical tokens | ||
| 64 | +```fortran | ||
| 65 | +function tokenize(input) result(tokens) | ||
| 66 | +``` | ||
| 67 | + | ||
| 68 | +**Token types:** Numbers, identifiers, operators, parentheses, brackets, etc. | ||
| 69 | + | ||
| 70 | +#### `fortbite_ast_m.f90` | ||
| 71 | +**Purpose:** Abstract Syntax Tree definition and memory management | ||
| 72 | +```fortran | ||
| 73 | +type :: ast_node_t | ||
| 74 | + integer :: node_type ! AST_LITERAL, AST_BINARY_OP, etc. | ||
| 75 | + character(len=:), allocatable :: identifier | ||
| 76 | + real(real64) :: value | ||
| 77 | + type(ast_node_t), pointer :: left, right | ||
| 78 | + ! ... other fields | ||
| 79 | +end type | ||
| 80 | +``` | ||
| 81 | + | ||
| 82 | +#### `fortbite_parser_m.f90` | ||
| 83 | +**Purpose:** Builds ASTs from token streams using recursive descent | ||
| 84 | +```fortran | ||
| 85 | +function parse_expression(tokens, error) result(root) | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +**Grammar hierarchy:** | ||
| 89 | +1. Assignment (`x := expr`) | ||
| 90 | +2. Logical operations | ||
| 91 | +3. Arithmetic operations (`+`, `-`, `*`, `/`, `**`) | ||
| 92 | +4. Function calls | ||
| 93 | +5. Primary expressions (numbers, variables, parentheses) | ||
| 94 | + | ||
| 95 | +### Evaluation System | ||
| 96 | + | ||
| 97 | +#### `fortbite_evaluator_m.f90` | ||
| 98 | +**Purpose:** Executes ASTs and manages variables | ||
| 99 | +```fortran | ||
| 100 | +function evaluate_expression(node, context, error) result(value) | ||
| 101 | +``` | ||
| 102 | + | ||
| 103 | +**Key patterns:** | ||
| 104 | +- Visitor pattern for AST traversal | ||
| 105 | +- Type checking and promotion | ||
| 106 | +- Error propagation | ||
| 107 | +- Variable context management | ||
| 108 | + | ||
| 109 | +**Recent improvements:** | ||
| 110 | +- Unified error handling with `quick_error()` helper | ||
| 111 | +- Consolidated function dispatch with helper functions | ||
| 112 | +- Streamlined argument validation | ||
| 113 | + | ||
| 114 | +#### `fortbite_arithmetic_m.f90` | ||
| 115 | +**Purpose:** Basic arithmetic operations with type promotion | ||
| 116 | +```fortran | ||
| 117 | +function add_values(left, right) result(value) | ||
| 118 | +function multiply_values(left, right) result(value) | ||
| 119 | +! etc. | ||
| 120 | +``` | ||
| 121 | + | ||
| 122 | +### Mathematical Functions | ||
| 123 | + | ||
| 124 | +#### `fortbite_functions_m.f90` | ||
| 125 | +**Purpose:** Advanced mathematical functions | ||
| 126 | +```fortran | ||
| 127 | +function eval_trigonometric(func_name, arg) result(value) | ||
| 128 | +function eval_hyperbolic(func_name, arg) result(value) | ||
| 129 | +function eval_logarithmic(func_name, arg) result(value) | ||
| 130 | +function eval_exponential(func_name, arg) result(value) | ||
| 131 | +function eval_statistical(func_name, arg) result(value) | ||
| 132 | +function eval_special(func_name, arg) result(value) | ||
| 133 | +function eval_complex_functions(func_name, arg) result(value) | ||
| 134 | +``` | ||
| 135 | + | ||
| 136 | +#### `fortbite_matrix_m.f90` | ||
| 137 | +**Purpose:** Linear algebra operations | ||
| 138 | +```fortran | ||
| 139 | +function matrix_transpose(matrix) result(result) | ||
| 140 | +function matrix_determinant(matrix) result(det) | ||
| 141 | +function matrix_inverse(matrix) result(inv) | ||
| 142 | +function matrix_solve(A, b) result(x) | ||
| 143 | +``` | ||
| 144 | + | ||
| 145 | +### User Interface | ||
| 146 | + | ||
| 147 | +#### `fortbite_io_m.f90` | ||
| 148 | +**Purpose:** REPL loop and user interaction | ||
| 149 | +```fortran | ||
| 150 | +subroutine repl_loop(context) | ||
| 151 | +function evaluate_math_expression(input, context) result(success) | ||
| 152 | +``` | ||
| 153 | + | ||
| 154 | +## Code Quality Improvements | ||
| 155 | + | ||
| 156 | +### Recent Refactoring (Completed) | ||
| 157 | + | ||
| 158 | +1. **Eliminated Code Duplication** | ||
| 159 | + - Created `validate_function_args()` helper | ||
| 160 | + - Added `validate_matrix_dims()` for dimension checking | ||
| 161 | + - Reduced ~120 lines of duplicate validation code | ||
| 162 | + | ||
| 163 | +2. **Unified Function Dispatch** | ||
| 164 | + - Added `eval_matrix_creation()` and `eval_matrix_operation()` helpers | ||
| 165 | + - Simplified case statements from 60+ lines to 1-2 lines | ||
| 166 | + - Maintained backward compatibility | ||
| 167 | + | ||
| 168 | +3. **Streamlined Matrix Creation** | ||
| 169 | + - Created `setup_matrix_base()` helper function | ||
| 170 | + - Reduced duplicate setup code across all matrix creation functions | ||
| 171 | + - All matrix functions now use consistent patterns | ||
| 172 | + | ||
| 173 | +4. **Enhanced Error Handling** | ||
| 174 | + - Added unified `fortbite_error_t` type | ||
| 175 | + - Created `create_error_value()` and `quick_error()` helpers | ||
| 176 | + - Replaced 15+ instances of hardcoded error returns | ||
| 177 | + | ||
| 178 | +## Development Guidelines | ||
| 179 | + | ||
| 180 | +### Coding Standards | ||
| 181 | + | ||
| 182 | +1. **Naming Conventions** | ||
| 183 | + - Modules: `fortbite_*_m.f90` | ||
| 184 | + - Functions: `verb_noun()` (e.g., `create_matrix()`) | ||
| 185 | + - Types: `*_t` suffix (e.g., `value_t`) | ||
| 186 | + - Constants: `UPPER_CASE` | ||
| 187 | + | ||
| 188 | +2. **Error Handling** | ||
| 189 | + - Always use unified error types | ||
| 190 | + - Prefer helper functions over manual error setting | ||
| 191 | + - Include descriptive error messages | ||
| 192 | + - Clean up resources on error paths | ||
| 193 | + | ||
| 194 | +3. **Memory Management** | ||
| 195 | + - Use allocatable arrays instead of pointers where possible | ||
| 196 | + - Always pair allocate/deallocate | ||
| 197 | + - Implement cleanup routines for complex types | ||
| 198 | + - Use `destroy_*()` functions consistently | ||
| 199 | + | ||
| 200 | +4. **Documentation** | ||
| 201 | + - Document all public interfaces with `!>` comments | ||
| 202 | + - Include usage examples for complex functions | ||
| 203 | + - Explain non-obvious algorithms | ||
| 204 | + - Keep README and guides up to date | ||
| 205 | + | ||
| 206 | +### Adding New Functions | ||
| 207 | + | ||
| 208 | +1. **Mathematical Functions** | ||
| 209 | + ```fortran | ||
| 210 | + ! In fortbite_functions_m.f90 | ||
| 211 | + case ('your_func') | ||
| 212 | + if (validate_args(...)) then | ||
| 213 | + result_val = create_scalar(your_calculation(x)) | ||
| 214 | + else | ||
| 215 | + result_val = create_error_value() | ||
| 216 | + end if | ||
| 217 | + ``` | ||
| 218 | + | ||
| 219 | +2. **Matrix Operations** | ||
| 220 | + ```fortran | ||
| 221 | + ! In fortbite_matrix_m.f90 | ||
| 222 | + function matrix_your_operation(matrix) result(result) | ||
| 223 | + type(value_t), intent(in) :: matrix | ||
| 224 | + type(value_t) :: result | ||
| 225 | + | ||
| 226 | + ! Validate matrix input | ||
| 227 | + ! Perform operation | ||
| 228 | + ! Return result | ||
| 229 | + end function | ||
| 230 | + ``` | ||
| 231 | + | ||
| 232 | +3. **Register in Evaluator** | ||
| 233 | + ```fortran | ||
| 234 | + ! In fortbite_evaluator_m.f90 | ||
| 235 | + case ('your_func') | ||
| 236 | + value = eval_your_category(node%function_name, args(1)) | ||
| 237 | + ``` | ||
| 238 | + | ||
| 239 | +### Testing Strategy | ||
| 240 | + | ||
| 241 | +#### Unit Tests (Recommended) | ||
| 242 | +```fortran | ||
| 243 | +program test_arithmetic | ||
| 244 | + use fortbite_arithmetic_m | ||
| 245 | + implicit none | ||
| 246 | + | ||
| 247 | + call test_addition() | ||
| 248 | + call test_multiplication() | ||
| 249 | + | ||
| 250 | +contains | ||
| 251 | + subroutine test_addition() | ||
| 252 | + ! Test cases | ||
| 253 | + end subroutine | ||
| 254 | +end program | ||
| 255 | +``` | ||
| 256 | + | ||
| 257 | +#### Integration Tests | ||
| 258 | +```bash | ||
| 259 | +# Test mathematical functions | ||
| 260 | +echo "sin(pi/2)" | ./fortbite | grep "1.0" | ||
| 261 | +echo "det([1,2;3,4])" | ./fortbite | grep "\-2" | ||
| 262 | +``` | ||
| 263 | + | ||
| 264 | +### Performance Considerations | ||
| 265 | + | ||
| 266 | +1. **Memory Usage** | ||
| 267 | + - Large matrices can consume significant memory | ||
| 268 | + - Consider implementing matrix size limits | ||
| 269 | + - Use efficient algorithms (O(n³) → O(n²·⁸) where possible) | ||
| 270 | + | ||
| 271 | +2. **Precision vs Speed** | ||
| 272 | + - High-precision mode is slower | ||
| 273 | + - Consider lazy precision conversion | ||
| 274 | + - Cache frequently used constants | ||
| 275 | + | ||
| 276 | +3. **Function Dispatch** | ||
| 277 | + - Current string-based dispatch is readable but not fastest | ||
| 278 | + - Consider hash tables for very large function sets | ||
| 279 | + - Profile before optimizing | ||
| 280 | + | ||
| 281 | +## Future Enhancements | ||
| 282 | + | ||
| 283 | +### Planned Features | ||
| 284 | +- **Automated Testing Suite** (in progress) | ||
| 285 | +- **Package Management** (fpm.toml ready) | ||
| 286 | +- **Extended Function Library** (statistical distributions, etc.) | ||
| 287 | +- **Performance Optimization** (BLAS integration) | ||
| 288 | + | ||
| 289 | +### Extension Points | ||
| 290 | +- **Custom Functions**: Easy to add via `fortbite_functions_m.f90` | ||
| 291 | +- **New Data Types**: Extend `value_t` for intervals, polynomials, etc. | ||
| 292 | +- **Alternative UIs**: Replace `fortbite_io_m.f90` for GUI/web interfaces | ||
| 293 | +- **File I/O**: Add import/export capabilities | ||
| 294 | + | ||
| 295 | +## Debugging Tips | ||
| 296 | + | ||
| 297 | +1. **Build with Debug Info** | ||
| 298 | + ```bash | ||
| 299 | + make clean && make FFLAGS="-g -fcheck=all -fbacktrace" | ||
| 300 | + ``` | ||
| 301 | + | ||
| 302 | +2. **Enable Warnings** | ||
| 303 | + ```bash | ||
| 304 | + make FFLAGS="-Wall -Wextra -Wconversion" | ||
| 305 | + ``` | ||
| 306 | + | ||
| 307 | +3. **Memory Debugging** | ||
| 308 | + ```bash | ||
| 309 | + valgrind --tool=memcheck ./build/bin/fortbite | ||
| 310 | + ``` | ||
| 311 | + | ||
| 312 | +4. **AST Debugging** | ||
| 313 | + - Add print statements in evaluator | ||
| 314 | + - Trace recursive descent parsing | ||
| 315 | + - Verify token sequences | ||
| 316 | + | ||
| 317 | +## Contributing | ||
| 318 | + | ||
| 319 | +1. **Fork and Branch** | ||
| 320 | + - Create feature branches | ||
| 321 | + - Use descriptive commit messages | ||
| 322 | + - Include tests for new functionality | ||
| 323 | + | ||
| 324 | +2. **Code Review Checklist** | ||
| 325 | + - [ ] Follows naming conventions | ||
| 326 | + - [ ] Includes error handling | ||
| 327 | + - [ ] Has documentation comments | ||
| 328 | + - [ ] Memory is properly managed | ||
| 329 | + - [ ] Tests pass (when implemented) | ||
| 330 | + | ||
| 331 | +3. **Performance Testing** | ||
| 332 | + - Profile before/after changes | ||
| 333 | + - Test with large matrices | ||
| 334 | + - Verify memory usage patterns | ||
| 335 | + | ||
| 336 | +--- | ||
| 337 | + | ||
| 338 | +*This developer guide provides the foundation for understanding and extending FORTBITE. For questions or clarifications, please refer to the source code comments and existing patterns.* | ||
QUICK_REFERENCE.mdadded@@ -0,0 +1,133 @@ | |||
| 1 | +# FORTBITE Quick Reference Card | ||
| 2 | + | ||
| 3 | +## Basic Operations | ||
| 4 | +``` | ||
| 5 | +2 + 3 # Addition | ||
| 6 | +5 - 1 # Subtraction | ||
| 7 | +4 * 6 # Multiplication | ||
| 8 | +8 / 2 # Division | ||
| 9 | +2**8 # Power | ||
| 10 | +17 % 5 # Modulo | ||
| 11 | +``` | ||
| 12 | + | ||
| 13 | +## Variables & Precision | ||
| 14 | +``` | ||
| 15 | +x := 42 # Variable assignment | ||
| 16 | +pi::50 # High precision (50 digits) | ||
| 17 | +precision # Show current precision | ||
| 18 | +``` | ||
| 19 | + | ||
| 20 | +## Mathematical Functions | ||
| 21 | + | ||
| 22 | +### Trigonometric | ||
| 23 | +``` | ||
| 24 | +sin(x) cos(x) tan(x) # Basic trig | ||
| 25 | +asin(x) acos(x) atan(x) # Inverse trig | ||
| 26 | +sec(x) csc(x) cot(x) # Additional trig | ||
| 27 | +``` | ||
| 28 | + | ||
| 29 | +### Hyperbolic | ||
| 30 | +``` | ||
| 31 | +sinh(x) cosh(x) tanh(x) # Basic hyperbolic | ||
| 32 | +asinh(x) acosh(x) atanh(x) # Inverse hyperbolic | ||
| 33 | +sech(x) csch(x) coth(x) # Additional hyperbolic | ||
| 34 | +``` | ||
| 35 | + | ||
| 36 | +### Logarithmic & Exponential | ||
| 37 | +``` | ||
| 38 | +log(x) ln(x) # Natural log | ||
| 39 | +log10(x) lg(x) # Base-10 log | ||
| 40 | +log2(x) # Base-2 log | ||
| 41 | +exp(x) exp2(x) # Exponential | ||
| 42 | +sqrt(x) abs(x) # Square root, absolute | ||
| 43 | +``` | ||
| 44 | + | ||
| 45 | +### Special Functions | ||
| 46 | +``` | ||
| 47 | +factorial(n) gamma(x) # Factorial, Gamma | ||
| 48 | +erf(x) erfc(x) # Error functions | ||
| 49 | +ceil(x) floor(x) # Ceiling, Floor | ||
| 50 | +round(x) frac(x) # Round, Fractional part | ||
| 51 | +``` | ||
| 52 | + | ||
| 53 | +## Complex Numbers | ||
| 54 | +``` | ||
| 55 | +3+4i # Complex literal | ||
| 56 | +(3,4) # Alternative syntax | ||
| 57 | +cmplx(3,4) # Function form | ||
| 58 | + | ||
| 59 | +real(z) imag(z) # Real/imaginary parts | ||
| 60 | +conj(z) abs(z) # Conjugate, magnitude | ||
| 61 | +arg(z) # Phase angle | ||
| 62 | +``` | ||
| 63 | + | ||
| 64 | +## Matrix Operations | ||
| 65 | + | ||
| 66 | +### Creation | ||
| 67 | +``` | ||
| 68 | +[1,2;3,4] # Matrix literal | ||
| 69 | +zeros(3,3) # 3×3 zero matrix | ||
| 70 | +ones(2,4) # 2×4 ones matrix | ||
| 71 | +eye(5) # 5×5 identity matrix | ||
| 72 | +``` | ||
| 73 | + | ||
| 74 | +### Operations | ||
| 75 | +``` | ||
| 76 | +transpose(A) # Matrix transpose | ||
| 77 | +det(A) # Determinant | ||
| 78 | +inv(A) # Matrix inverse | ||
| 79 | +trace(A) # Trace (diagonal sum) | ||
| 80 | +rank(A) # Matrix rank | ||
| 81 | +solve(A,b) # Solve Ax = b | ||
| 82 | +``` | ||
| 83 | + | ||
| 84 | +### Statistics | ||
| 85 | +``` | ||
| 86 | +sum(M) # Sum all elements | ||
| 87 | +mean(M) # Average | ||
| 88 | +std(M) # Standard deviation | ||
| 89 | +``` | ||
| 90 | + | ||
| 91 | +## Built-in Constants | ||
| 92 | +``` | ||
| 93 | +pi # 3.14159... | ||
| 94 | +e # 2.71828... | ||
| 95 | +i # Imaginary unit | ||
| 96 | +``` | ||
| 97 | + | ||
| 98 | +## Commands | ||
| 99 | +``` | ||
| 100 | +help # Show help | ||
| 101 | +exit # Quit program | ||
| 102 | +clear # Clear screen | ||
| 103 | +precision # Show precision info | ||
| 104 | +info # System information | ||
| 105 | +``` | ||
| 106 | + | ||
| 107 | +## Syntax Rules | ||
| 108 | +- `:=` for assignment | ||
| 109 | +- `::` for precision control | ||
| 110 | +- `;` separates matrix rows | ||
| 111 | +- `,` separates matrix columns | ||
| 112 | +- `i` suffix for imaginary numbers | ||
| 113 | +- `()` for function calls and grouping | ||
| 114 | +- `[]` for matrix literals | ||
| 115 | + | ||
| 116 | +## Examples | ||
| 117 | +``` | ||
| 118 | +# Scientific calculation | ||
| 119 | +g := 9.81 | ||
| 120 | +velocity := sqrt(2 * g * height) | ||
| 121 | + | ||
| 122 | +# Linear algebra | ||
| 123 | +A := [2,1;1,3] | ||
| 124 | +b := [5;7] | ||
| 125 | +x := solve(A,b) | ||
| 126 | + | ||
| 127 | +# Complex analysis | ||
| 128 | +z := exp(i * pi/4) | ||
| 129 | +magnitude := abs(z) | ||
| 130 | + | ||
| 131 | +# High precision | ||
| 132 | +pi_precise := pi::100 | ||
| 133 | +``` | ||
USAGE_GUIDE.mdadded@@ -0,0 +1,489 @@ | |||
| 1 | +# FORTBITE Usage Guide | ||
| 2 | + | ||
| 3 | +**FORTBITE** (Fortran-based Operations on Real-Time Backend for Interactive Technical Expression) is a high-precision mathematical calculator built with modern Fortran. It provides advanced mathematical capabilities including matrix operations, complex numbers, and high-precision arithmetic. | ||
| 4 | + | ||
| 5 | +## Table of Contents | ||
| 6 | +- [Getting Started](#getting-started) | ||
| 7 | +- [Basic Arithmetic](#basic-arithmetic) | ||
| 8 | +- [Variables](#variables) | ||
| 9 | +- [Precision Control](#precision-control) | ||
| 10 | +- [Mathematical Functions](#mathematical-functions) | ||
| 11 | +- [Complex Numbers](#complex-numbers) | ||
| 12 | +- [Matrix Operations](#matrix-operations) | ||
| 13 | +- [Advanced Features](#advanced-features) | ||
| 14 | +- [Command Reference](#command-reference) | ||
| 15 | + | ||
| 16 | +## Getting Started | ||
| 17 | + | ||
| 18 | +### Building FORTBITE | ||
| 19 | +```bash | ||
| 20 | +make clean && make | ||
| 21 | +``` | ||
| 22 | + | ||
| 23 | +### Running FORTBITE | ||
| 24 | +```bash | ||
| 25 | +./build/bin/fortbite | ||
| 26 | +``` | ||
| 27 | + | ||
| 28 | +### Basic Usage | ||
| 29 | +FORTBITE uses an interactive REPL (Read-Eval-Print Loop). Simply type mathematical expressions and press Enter: | ||
| 30 | + | ||
| 31 | +``` | ||
| 32 | +fortbite> 2 + 3 | ||
| 33 | +5 | ||
| 34 | +fortbite> sin(pi/4) | ||
| 35 | +0.7071067811865476 | ||
| 36 | +fortbite> exit | ||
| 37 | +``` | ||
| 38 | + | ||
| 39 | +## Basic Arithmetic | ||
| 40 | + | ||
| 41 | +### Operators | ||
| 42 | +- `+` Addition | ||
| 43 | +- `-` Subtraction | ||
| 44 | +- `*` Multiplication | ||
| 45 | +- `/` Division | ||
| 46 | +- `**` Exponentiation (power) | ||
| 47 | +- `%` Modulo | ||
| 48 | + | ||
| 49 | +### Examples | ||
| 50 | +``` | ||
| 51 | +fortbite> 15 + 25 | ||
| 52 | +40 | ||
| 53 | +fortbite> 10 - 3.5 | ||
| 54 | +6.5 | ||
| 55 | +fortbite> 4 * 7 | ||
| 56 | +28 | ||
| 57 | +fortbite> 22 / 7 | ||
| 58 | +3.142857142857143 | ||
| 59 | +fortbite> 2**10 | ||
| 60 | +1024 | ||
| 61 | +fortbite> 17 % 5 | ||
| 62 | +2 | ||
| 63 | +``` | ||
| 64 | + | ||
| 65 | +### Order of Operations | ||
| 66 | +FORTBITE follows standard mathematical precedence: | ||
| 67 | +1. Parentheses `()` | ||
| 68 | +2. Exponentiation `**` | ||
| 69 | +3. Multiplication `*`, Division `/`, Modulo `%` | ||
| 70 | +4. Addition `+`, Subtraction `-` | ||
| 71 | + | ||
| 72 | +``` | ||
| 73 | +fortbite> 2 + 3 * 4 | ||
| 74 | +14 | ||
| 75 | +fortbite> (2 + 3) * 4 | ||
| 76 | +20 | ||
| 77 | +fortbite> 2**3**2 | ||
| 78 | +512 | ||
| 79 | +``` | ||
| 80 | + | ||
| 81 | +## Variables | ||
| 82 | + | ||
| 83 | +### Variable Assignment | ||
| 84 | +Use `:=` to assign values to variables: | ||
| 85 | + | ||
| 86 | +``` | ||
| 87 | +fortbite> x := 42 | ||
| 88 | +42 | ||
| 89 | +fortbite> y := x * 2 | ||
| 90 | +84 | ||
| 91 | +fortbite> radius := 5.0 | ||
| 92 | +5 | ||
| 93 | +fortbite> area := pi * radius**2 | ||
| 94 | +78.53981633974483 | ||
| 95 | +``` | ||
| 96 | + | ||
| 97 | +### Variable Names | ||
| 98 | +- Must start with a letter | ||
| 99 | +- Can contain letters, numbers, and underscores | ||
| 100 | +- Case-sensitive | ||
| 101 | + | ||
| 102 | +``` | ||
| 103 | +fortbite> my_var := 10 | ||
| 104 | +10 | ||
| 105 | +fortbite> MyVar := 20 | ||
| 106 | +20 | ||
| 107 | +fortbite> coefficient_1 := 3.14 | ||
| 108 | +3.14 | ||
| 109 | +``` | ||
| 110 | + | ||
| 111 | +## Precision Control | ||
| 112 | + | ||
| 113 | +### Setting Precision | ||
| 114 | +Use `::` to specify the number of decimal digits for high-precision calculations: | ||
| 115 | + | ||
| 116 | +``` | ||
| 117 | +fortbite> pi | ||
| 118 | +3.141592653589793 | ||
| 119 | +fortbite> pi::50 | ||
| 120 | +3.1415926535897932384626433832795028841971693993751 | ||
| 121 | +fortbite> 1/3::25 | ||
| 122 | +0.3333333333333333333333333 | ||
| 123 | +``` | ||
| 124 | + | ||
| 125 | +### Current Precision | ||
| 126 | +Check current precision settings: | ||
| 127 | +``` | ||
| 128 | +fortbite> precision | ||
| 129 | +Current precision: Double Precision | ||
| 130 | +Decimal digits: 15 | ||
| 131 | +Exponent range: ±307 | ||
| 132 | +``` | ||
| 133 | + | ||
| 134 | +## Mathematical Functions | ||
| 135 | + | ||
| 136 | +### Trigonometric Functions | ||
| 137 | +``` | ||
| 138 | +fortbite> sin(pi/6) | ||
| 139 | +0.49999999999999994 | ||
| 140 | +fortbite> cos(0) | ||
| 141 | +1 | ||
| 142 | +fortbite> tan(pi/4) | ||
| 143 | +0.9999999999999999 | ||
| 144 | +``` | ||
| 145 | + | ||
| 146 | +**Available functions:** | ||
| 147 | +- `sin(x)`, `cos(x)`, `tan(x)` - Basic trigonometric functions | ||
| 148 | +- `asin(x)`, `acos(x)`, `atan(x)` - Inverse trigonometric functions | ||
| 149 | +- `sec(x)`, `csc(x)`, `cot(x)` - Additional trigonometric functions | ||
| 150 | + | ||
| 151 | +**Alternative names:** | ||
| 152 | +- `arcsin(x)` = `asin(x)` | ||
| 153 | +- `arccos(x)` = `acos(x)` | ||
| 154 | +- `arctan(x)` = `atan(x)` | ||
| 155 | + | ||
| 156 | +### Hyperbolic Functions | ||
| 157 | +``` | ||
| 158 | +fortbite> sinh(1) | ||
| 159 | +1.1752011936438014 | ||
| 160 | +fortbite> cosh(0) | ||
| 161 | +1 | ||
| 162 | +fortbite> tanh(2) | ||
| 163 | +0.9640275800758169 | ||
| 164 | +``` | ||
| 165 | + | ||
| 166 | +**Available functions:** | ||
| 167 | +- `sinh(x)`, `cosh(x)`, `tanh(x)` - Basic hyperbolic functions | ||
| 168 | +- `asinh(x)`, `acosh(x)`, `atanh(x)` - Inverse hyperbolic functions | ||
| 169 | +- `sech(x)`, `csch(x)`, `coth(x)` - Additional hyperbolic functions | ||
| 170 | + | ||
| 171 | +### Logarithmic and Exponential Functions | ||
| 172 | +``` | ||
| 173 | +fortbite> log(e) | ||
| 174 | +1 | ||
| 175 | +fortbite> log10(100) | ||
| 176 | +2 | ||
| 177 | +fortbite> exp(1) | ||
| 178 | +2.718281828459045 | ||
| 179 | +fortbite> sqrt(16) | ||
| 180 | +4 | ||
| 181 | +``` | ||
| 182 | + | ||
| 183 | +**Available functions:** | ||
| 184 | +- `log(x)`, `ln(x)` - Natural logarithm | ||
| 185 | +- `log10(x)`, `lg(x)` - Base-10 logarithm | ||
| 186 | +- `log2(x)` - Base-2 logarithm | ||
| 187 | +- `exp(x)` - Exponential function (e^x) | ||
| 188 | +- `exp2(x)` - Base-2 exponential (2^x) | ||
| 189 | +- `exp10(x)` - Base-10 exponential (10^x) | ||
| 190 | +- `expm1(x)` - exp(x) - 1 (accurate for small x) | ||
| 191 | + | ||
| 192 | +### Special Functions | ||
| 193 | +``` | ||
| 194 | +fortbite> factorial(5) | ||
| 195 | +120 | ||
| 196 | +fortbite> gamma(4) | ||
| 197 | +6 | ||
| 198 | +fortbite> erf(1) | ||
| 199 | +0.8427007929497149 | ||
| 200 | +fortbite> abs(-5) | ||
| 201 | +5 | ||
| 202 | +``` | ||
| 203 | + | ||
| 204 | +**Available functions:** | ||
| 205 | +- `factorial(n)`, `fact(n)` - Factorial function | ||
| 206 | +- `gamma(x)` - Gamma function | ||
| 207 | +- `lgamma(x)`, `loggamma(x)` - Log-gamma function | ||
| 208 | +- `erf(x)` - Error function | ||
| 209 | +- `erfc(x)` - Complementary error function | ||
| 210 | +- `abs(x)` - Absolute value | ||
| 211 | +- `sqrt(x)` - Square root | ||
| 212 | +- `ceil(x)`, `ceiling(x)` - Ceiling function | ||
| 213 | +- `floor(x)` - Floor function | ||
| 214 | +- `round(x)`, `nint(x)` - Round to nearest integer | ||
| 215 | +- `frac(x)`, `fraction(x)` - Fractional part | ||
| 216 | + | ||
| 217 | +## Complex Numbers | ||
| 218 | + | ||
| 219 | +### Creating Complex Numbers | ||
| 220 | +Multiple ways to create complex numbers: | ||
| 221 | + | ||
| 222 | +``` | ||
| 223 | +fortbite> 3+4i | ||
| 224 | +3+4i | ||
| 225 | +fortbite> (3,4) | ||
| 226 | +3+4i | ||
| 227 | +fortbite> cmplx(3,4) | ||
| 228 | +3+4i | ||
| 229 | +``` | ||
| 230 | + | ||
| 231 | +### Complex Functions | ||
| 232 | +``` | ||
| 233 | +fortbite> z := 3+4i | ||
| 234 | +3+4i | ||
| 235 | +fortbite> real(z) | ||
| 236 | +3 | ||
| 237 | +fortbite> imag(z) | ||
| 238 | +4 | ||
| 239 | +fortbite> abs(z) | ||
| 240 | +5 | ||
| 241 | +fortbite> conj(z) | ||
| 242 | +3-4i | ||
| 243 | +fortbite> arg(z) | ||
| 244 | +0.9272952180016122 | ||
| 245 | +``` | ||
| 246 | + | ||
| 247 | +**Available complex functions:** | ||
| 248 | +- `real(z)`, `re(z)` - Real part | ||
| 249 | +- `imag(z)`, `im(z)` - Imaginary part | ||
| 250 | +- `conj(z)`, `conjugate(z)` - Complex conjugate | ||
| 251 | +- `abs(z)`, `cabs(z)`, `modulus(z)` - Magnitude/modulus | ||
| 252 | +- `arg(z)`, `phase(z)`, `angle(z)` - Phase angle | ||
| 253 | + | ||
| 254 | +### Complex Arithmetic | ||
| 255 | +``` | ||
| 256 | +fortbite> (3+4i) + (1+2i) | ||
| 257 | +4+6i | ||
| 258 | +fortbite> (3+4i) * (1+2i) | ||
| 259 | +-5+10i | ||
| 260 | +fortbite> (3+4i) / (1+2i) | ||
| 261 | +2.2-0.4i | ||
| 262 | +``` | ||
| 263 | + | ||
| 264 | +## Matrix Operations | ||
| 265 | + | ||
| 266 | +### Creating Matrices | ||
| 267 | + | ||
| 268 | +#### Matrix Literals | ||
| 269 | +``` | ||
| 270 | +fortbite> [1,2;3,4] | ||
| 271 | +[2x2 matrix] | ||
| 272 | + 1 2 | ||
| 273 | + 3 4 | ||
| 274 | +``` | ||
| 275 | + | ||
| 276 | +#### Special Matrices | ||
| 277 | +``` | ||
| 278 | +fortbite> zeros(3,3) | ||
| 279 | +[3x3 matrix] | ||
| 280 | + 0 0 0 | ||
| 281 | + 0 0 0 | ||
| 282 | + 0 0 0 | ||
| 283 | + | ||
| 284 | +fortbite> ones(2,3) | ||
| 285 | +[2x3 matrix] | ||
| 286 | + 1 1 1 | ||
| 287 | + 1 1 1 | ||
| 288 | + | ||
| 289 | +fortbite> eye(3) | ||
| 290 | +[3x3 matrix] | ||
| 291 | + 1 0 0 | ||
| 292 | + 0 1 0 | ||
| 293 | + 0 0 1 | ||
| 294 | +``` | ||
| 295 | + | ||
| 296 | +**Matrix creation functions:** | ||
| 297 | +- `zeros(n)` - n×n zero matrix | ||
| 298 | +- `zeros(m,n)` - m×n zero matrix | ||
| 299 | +- `ones(n)` - n×n ones matrix | ||
| 300 | +- `ones(m,n)` - m×n ones matrix | ||
| 301 | +- `eye(n)` - n×n identity matrix | ||
| 302 | + | ||
| 303 | +### Matrix Operations | ||
| 304 | +``` | ||
| 305 | +fortbite> A := [1,2;3,4] | ||
| 306 | +[2x2 matrix] | ||
| 307 | + 1 2 | ||
| 308 | + 3 4 | ||
| 309 | + | ||
| 310 | +fortbite> transpose(A) | ||
| 311 | +[2x2 matrix] | ||
| 312 | + 1 3 | ||
| 313 | + 2 4 | ||
| 314 | + | ||
| 315 | +fortbite> det(A) | ||
| 316 | +-2 | ||
| 317 | + | ||
| 318 | +fortbite> inv(A) | ||
| 319 | +[2x2 matrix] | ||
| 320 | + -2 1 | ||
| 321 | + 1.5 -0.5 | ||
| 322 | +``` | ||
| 323 | + | ||
| 324 | +**Available matrix functions:** | ||
| 325 | +- `transpose(A)`, `trans(A)` - Matrix transpose | ||
| 326 | +- `det(A)`, `determinant(A)` - Determinant | ||
| 327 | +- `inv(A)`, `inverse(A)` - Matrix inverse | ||
| 328 | +- `trace(A)` - Matrix trace (sum of diagonal elements) | ||
| 329 | +- `rank(A)` - Matrix rank | ||
| 330 | +- `solve(A,b)` - Solve linear system Ax = b | ||
| 331 | + | ||
| 332 | +### Matrix Statistics | ||
| 333 | +``` | ||
| 334 | +fortbite> M := [1,2,3;4,5,6] | ||
| 335 | +[2x3 matrix] | ||
| 336 | + 1 2 3 | ||
| 337 | + 4 5 6 | ||
| 338 | + | ||
| 339 | +fortbite> sum(M) | ||
| 340 | +21 | ||
| 341 | +fortbite> mean(M) | ||
| 342 | +3.5 | ||
| 343 | +fortbite> std(M) | ||
| 344 | +1.8708286933869707 | ||
| 345 | +``` | ||
| 346 | + | ||
| 347 | +**Statistical functions:** | ||
| 348 | +- `sum(M)` - Sum of all elements | ||
| 349 | +- `mean(M)`, `average(M)` - Mean of all elements | ||
| 350 | +- `std(M)`, `stddev(M)` - Standard deviation | ||
| 351 | + | ||
| 352 | +## Advanced Features | ||
| 353 | + | ||
| 354 | +### Built-in Constants | ||
| 355 | +``` | ||
| 356 | +fortbite> pi | ||
| 357 | +3.141592653589793 | ||
| 358 | +fortbite> e | ||
| 359 | +2.718281828459045 | ||
| 360 | +fortbite> i | ||
| 361 | +0+1i | ||
| 362 | +``` | ||
| 363 | + | ||
| 364 | +### Chaining Operations | ||
| 365 | +``` | ||
| 366 | +fortbite> result := sin(pi/4) + cos(pi/4) | ||
| 367 | +1.4142135623730951 | ||
| 368 | +fortbite> matrix_result := det(inv([1,2;3,4])) | ||
| 369 | +-0.5 | ||
| 370 | +``` | ||
| 371 | + | ||
| 372 | +### High-Precision Calculations | ||
| 373 | +``` | ||
| 374 | +fortbite> pi::100 | ||
| 375 | +3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 | ||
| 376 | + | ||
| 377 | +fortbite> x := 1/3::50 | ||
| 378 | +0.33333333333333333333333333333333333333333333333333 | ||
| 379 | + | ||
| 380 | +fortbite> y := x * 3::50 | ||
| 381 | +0.99999999999999999999999999999999999999999999999999 | ||
| 382 | +``` | ||
| 383 | + | ||
| 384 | +## Command Reference | ||
| 385 | + | ||
| 386 | +### Interactive Commands | ||
| 387 | +- `help` - Display help information | ||
| 388 | +- `exit` - Exit FORTBITE | ||
| 389 | +- `clear` - Clear screen (if supported) | ||
| 390 | +- `precision` - Show current precision settings | ||
| 391 | +- `info` - Display system information | ||
| 392 | + | ||
| 393 | +### Special Syntax | ||
| 394 | +- `:=` - Variable assignment | ||
| 395 | +- `::` - Precision specification | ||
| 396 | +- `;` - Matrix row separator in literals | ||
| 397 | +- `,` - Matrix column separator in literals | ||
| 398 | +- `i` - Imaginary unit suffix | ||
| 399 | +- `()` - Function calls and grouping | ||
| 400 | +- `[]` - Matrix literals | ||
| 401 | + | ||
| 402 | +## Examples and Use Cases | ||
| 403 | + | ||
| 404 | +### Scientific Calculations | ||
| 405 | +```fortran | ||
| 406 | +! Calculate projectile motion | ||
| 407 | +fortbite> g := 9.81 | ||
| 408 | +9.81 | ||
| 409 | +fortbite> v0 := 50 | ||
| 410 | +50 | ||
| 411 | +fortbite> angle := 45 * pi/180 | ||
| 412 | +0.7853981633974483 | ||
| 413 | +fortbite> time_flight := 2 * v0 * sin(angle) / g | ||
| 414 | +7.214390675673431 | ||
| 415 | +fortbite> max_height := (v0 * sin(angle))**2 / (2*g) | ||
| 416 | +63.775510204081634 | ||
| 417 | +``` | ||
| 418 | + | ||
| 419 | +### Linear Algebra | ||
| 420 | +```fortran | ||
| 421 | +! Solve system of equations: 2x + 3y = 8, x - y = 1 | ||
| 422 | +fortbite> A := [2,3;1,-1] | ||
| 423 | +[2x2 matrix] | ||
| 424 | + 2 3 | ||
| 425 | + 1 -1 | ||
| 426 | +fortbite> b := [8;1] | ||
| 427 | +[2x1 matrix] | ||
| 428 | + 8 | ||
| 429 | + 1 | ||
| 430 | +fortbite> solution := solve(A,b) | ||
| 431 | +[2x1 matrix] | ||
| 432 | + 2.2 | ||
| 433 | + 1.2 | ||
| 434 | +``` | ||
| 435 | + | ||
| 436 | +### Complex Analysis | ||
| 437 | +```fortran | ||
| 438 | +! Euler's formula verification: e^(iπ) + 1 = 0 | ||
| 439 | +fortbite> result := exp(i*pi) + 1 | ||
| 440 | +1.2246467991473532e-16+0i | ||
| 441 | +! (Very close to zero, within numerical precision) | ||
| 442 | +``` | ||
| 443 | + | ||
| 444 | +### Statistical Analysis | ||
| 445 | +```fortran | ||
| 446 | +! Analyze dataset | ||
| 447 | +fortbite> data := [1,2,3,4,5,6,7,8,9,10] | ||
| 448 | +[1x10 matrix] | ||
| 449 | + 1 2 3 4 5 6 7 8 9 10 | ||
| 450 | +fortbite> data_mean := mean(data) | ||
| 451 | +5.5 | ||
| 452 | +fortbite> data_std := std(data) | ||
| 453 | +3.0276503540974917 | ||
| 454 | +``` | ||
| 455 | + | ||
| 456 | +## Tips and Best Practices | ||
| 457 | + | ||
| 458 | +1. **Use descriptive variable names** for complex calculations | ||
| 459 | +2. **Specify precision** when you need more than 15 decimal digits | ||
| 460 | +3. **Check matrix dimensions** before operations (FORTBITE will warn you) | ||
| 461 | +4. **Use parentheses** to clarify complex expressions | ||
| 462 | +5. **Store intermediate results** in variables for multi-step calculations | ||
| 463 | + | ||
| 464 | +## Error Handling | ||
| 465 | + | ||
| 466 | +FORTBITE provides helpful error messages for common mistakes: | ||
| 467 | + | ||
| 468 | +``` | ||
| 469 | +fortbite> sqrt(-1) | ||
| 470 | +Evaluation error: sqrt() argument must be non-negative | ||
| 471 | + | ||
| 472 | +fortbite> solve([1,2]) | ||
| 473 | +Evaluation error: solve() expects 2 arguments: solve(A, b) | ||
| 474 | + | ||
| 475 | +fortbite> unknown_func(5) | ||
| 476 | +Evaluation error: Unknown function: unknown_func | ||
| 477 | +``` | ||
| 478 | + | ||
| 479 | +## Limitations | ||
| 480 | + | ||
| 481 | +- Matrix operations are limited to reasonable sizes (memory dependent) | ||
| 482 | +- Complex numbers use double precision internally | ||
| 483 | +- Some functions may have domain restrictions (e.g., sqrt of negative numbers) | ||
| 484 | +- High precision mode may be slower for complex calculations | ||
| 485 | + | ||
| 486 | +--- | ||
| 487 | + | ||
| 488 | +*FORTBITE - High-Precision Calculator, Modern Fortran Edition* | ||
| 489 | +*Built with modern Fortran 2008+ standards* | ||