# FortranFlowMap

**Repository Path**: suyuexinghen28/FortranFlowMap

## Basic Information

- **Project Name**: FortranFlowMap
- **Description**: 该程序是一个用于分析Fortran代码（特别是F90文件）以提取和可视化函数调用关系的工具。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-01
- **Last Updated**: 2025-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FortranFlowMap

The program is a tool for analyzing Fortran code (specifically F90 files) to extract and visualize function call relationships.

Key features of the program:
1. It parses Fortran files to extract subroutines, programs, and function calls
2. It builds call trees (both downstream and upstream) to visualize function relationships
3. It can filter the trees to focus on important nodes based on configurable depths
4. It can generate text-based tree visualizations of function calls
5. It can extract computation steps from source code
6. It can identify the most frequently called functions
7. It can generate call chains

Main functionalities:
- Parse F90 files recursively or in specific directories
- Build function call hierarchies (what functions are called by a function)
- Build reverse call hierarchies (what functions call a function)
- Filter trees based on configurable depths and modes
- Visualize trees as text-based structures
- Generate reports on most frequently called functions
- Extract and analyze computation steps from source code
- Handle function aliases and name mapping

## Installation

You can install FortranFlowMap in the following ways:

### From Source

```bash
# Clone the repository
git clone https://github.com/yourusername/FortranFlowMap.git
cd FortranFlowMap

# Install for the current user
pip install --user .

# Or system-wide installation (requires administrator privileges)
sudo pip install .
```

After installation, you can run the `FortranFlowMap.py` command from any directory.


# FortranFlowMap.py - Fortran Code Analysis Tool

## Introduction

FortranFlowMap.py is a powerful tool for analyzing and visualizing function call relationships in Fortran 90 code bases. It helps you understand complex code structures by extracting subroutines, their relationships, and generating call trees that show how different parts of the codebase interact. It is designed for analyzing codebases related to meteorological models such as drp4dvar, CAM or GSI, but it is equally applicable to Fortran programs in other fields.

## Features

- Extract subroutines, programs, and function calls from Fortran 90 files
- Generate function call trees (downstream: what functions a routine calls)
- Generate caller trees (upstream: what functions call a routine)
- Identify frequently called functions with usage statistics
- Extract computation steps from source code
- Handle function aliases and name mappings
- Filter results based on configurable depth settings
- Export results to text files for documentation

## Basic Usage

1. Set the analysis parameters at the bottom of the script:
   ```python
   analysis_flag = "drp4dvar"  # The main program name
   filter_depth = {"down": 7, "up": 1}  # Configure depth for different directions
   filter_mode = "none"  # "down", "up", "both", or "none"
   ```

2. Configure source directories and target functions:
   ```python
   src_directory = ['../src/', '../lib/']
   user_root_name = "drp4dvar_driver"  # Main program to analyze
   target_subroutine = "minimize_cg"   # Specific routine to focus on
   ```

3. Run the script:
   ```
   python FortranFlowMap.py
   ```

Alternatively, you can run the script using command line arguments:

```bash
python FortranFlowMap.py --src ./ --root GRAPES --filter grapes_error_fatal,global2patch,grapes_bcast
```

You can view the help information using:
```bash
python FortranFlowMap.py --help
```

Help output:
```
usage: FortranFlowMap.py [-h] [--src SRC [SRC ...]] [--target TARGET] [--root ROOT]
                         [--debug] [--filter FILTER]

Fortran Flow Map: Analyze Fortran code structure and call relationships

options:
  -h, --help           show this help message and exit
  --src SRC [SRC ...]  Source directories to scan for Fortran files
  --target TARGET      Target subroutine name for specific analysis
  --root ROOT          Root program name for analysis
  --debug              Enable debug output
  --filter FILTER      Comma-separated list of additional function names to filter out
                       (e.g., "grapes_error_fatal,global2patch")
```

Command line options explanation:
- `--src SRC [SRC ...]`: Specify directories to scan for Fortran source files, can provide multiple directories
- `--target TARGET`: Specify a subroutine name for detailed analysis (optional)
- `--root ROOT`: Specify the root program name for analysis (optional)
- `--debug`: Enable debug output to display more information about the analysis process
- `--filter FILTER`: Specify a comma-separated list of function names to filter out from the analysis, e.g.: `grapes_error_fatal,global2patch`

Examples of specifying multiple source directories:
```bash
# Analyze Fortran files in both src/ and lib/ directories
python FortranFlowMap.py --src src/ lib/ --root GRAPES

# Analyze three different directory paths
python FortranFlowMap.py --src ../model/src/ ./lib/ ../external/utils/ --root GRAPES
```
The purpose of specifying multiple source code directories is to avoid multiple branches and duplicate function names when recursing subdirectories, so that branch paths that need to be analyzed can be manually specified.

## Output Files

The script generates several output files:

- `tree_[root_name].txt`: Complete call tree starting from the main program
- `analysis_[target_subroutine].txt`: Analysis of the target subroutine, including what calls it and what it calls
- `chains_[root_name].txt`: Function call chains showing execution paths
- `steps_[root_name].txt`: Processing steps with source code analysis of all non-leaf nodes

## Advanced Features

- **Filtering**: Control the depth of the call tree with `filter_depth` and `filter_mode`
- **Alias Resolution**: The script automatically handles function aliases and generic interfaces
- **Computation Analysis**: Extract key computation statements from source code
- **Statistical Analysis**: Identify most frequently called functions

## Customization

You can customize the analysis by modifying these parameters:

- `filter_depth`: Control the depth of the call tree (in up mode, a higher value displays a longer chain of call relationships; in down mode, a higher value filters more leaf nodes to make the main structure clearer)
- `filter_mode`: Choose which direction to filter ("down", "up", "both", or "none")
- `src_directory`: Specify where to look for source files
- `isRecursive`: Enable/disable recursive directory scanning

## Requirements

- Python 3.x
- `chardet` library (for encoding detection)

This tool is especially useful for understanding large Fortran codebases such as scientific models, weather forecasting systems, or legacy applications.