fortrangoingonforty/fortbite / a9a7856

Browse files

Add all documentation files

Authored by espadonne
SHA
a9a7856383a5b46ae172e490d376bfbf1c8f5591
Parents
6379d17
Tree
42f238f

3 changed files

StatusFile+-
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*