--------------------------------------------------------
Instituto Nacional de Pesquisas Espaciais - INPE
Coordenacao-Geral de Ciencias da Terra - CGCT
Divisao de Impactos, Adaptacao e Vulnerabilidade - DIIAV

Projeto: SisMOM
Sistema de Monitoramento e Modelagem Oceanica e Costeira
--------------------------------------------------------
Manual de instalacao, configuracao e execucao - Produto Fortran.
--------------------------------------------------------

================================================================================
 CONVERSAO NetCDF -> TXT  |  SOLUCAO EM FORTRAN
 Manual de instalacao, configuracao e execucao
================================================================================

VISAO GERAL
-----------
Este programa le as saidas dos modelos atmosferico (Eta/BESM) e oceanico (MOM6)
em formato NetCDF e gera arquivos TXT no formato Fortran do usuario, interpolando
para as 3 grades regulares da costa do Brasil (GRID_EQ, GRID_NE, GRID_SE).

Saidas geradas:
  - Ventos:    GRID_<grade>/WINDS/winds_aaaammdd_hh.txt
  - Correntes: GRID_<grade>/CURRENTS/currents_aaaammdd_hh.txt
  - Um arquivo por timestep (hora).

E necessario COMPILAR o programa uma vez na maquina do usuario.


1. PRE-REQUISITOS
-----------------
  - Compilador gfortran (GNU Fortran). Testado com a versao 13.
  - Biblioteca netCDF para Fortran (netCDF-Fortran) e suas dependencias
    (netCDF-C, HDF5). Inclui o utilitario "nf-config".
  - make.

Instalacao dos pre-requisitos:

  Ubuntu/Debian:
    sudo apt update
    sudo apt install -y gfortran libnetcdff-dev make
    (libnetcdff-dev puxa automaticamente netCDF-C e HDF5)

  RHEL / Rocky / Fedora:
    sudo dnf install -y gcc-gfortran netcdf-fortran-devel make

Verifique apos instalar:
    gfortran --version
    nf-config --version
    nf-config --flibs        (deve listar -lnetcdff -lnetcdf ...)

Se a maquina de producao NAO tem internet:
  - Baixe os pacotes em outra maquina com internet e o MESMO sistema/versao:
        Ubuntu:  apt-get download gfortran libnetcdff-dev libnetcdf-dev libhdf5-dev ... (e dependencias)
        Depois:  sudo dpkg -i *.deb
  - Em seguida compile normalmente (passo 3).


2. ESTRUTURA DE DIRETORIOS ESPERADA
-----------------------------------
O programa espera (caminhos configuraveis no config.nml):

  <projeto>/
    config.nml                      <- arquivo de configuracao
    src/fortran/                    <- codigo-fonte e Makefile
    datain/                         <- ENTRADA: arquivos NetCDF
        Eta03_BESM_..._2D.new.nc
        20260609.uo.new.nc
        20260609.vo.new.nc
        20260609.thetao.new.nc
        20260609.so.new.nc
    dataout/googledrive_grid/       <- SAIDA: grades do usuario
        GRID_EQ/  grid_EQ.txt  WINDS/  CURRENTS/
        GRID_NE/  grid_NE.txt  WINDS/  CURRENTS/
        GRID_SE/  grid_SE.txt  WINDS/  CURRENTS/

Os arquivos de entrada em datain/ NAO sao modificados (abertos somente leitura).

ARQUIVOS DO PRODUTO (dentro de src/fortran/):

  Makefile
      Regras de compilacao. Usa o nf-config para achar os caminhos do NetCDF.
      Comandos: "make" (compila) e "make clean" (limpa).

  nc2txt.f90
      Programa principal. Le a configuracao, resolve a fonte atmosferica
      (combinada ou separada) e percorre cada grade e cada timestep, chamando a
      leitura, a interpolacao e a escrita de ventos e correntes.

  mod_kinds.f90
      Define a precisao numerica usada no codigo (simples e dupla).

  mod_config.f90
      Le o arquivo de configuracao config.nml (grupo NAMELIST &config).

  mod_grid.f90
      Le as grades do usuario (grid_XX.txt): dimensoes, longitude, latitude,
      profundidade e mascara de terra/mar.

  mod_netcdf.f90
      Rotinas de leitura dos arquivos NetCDF (campos 2D atmosfericos e 3D
      oceanicos, coordenadas e numero de timesteps), tratando o valor de
      preenchimento (fill) da entrada.

  mod_interp.f90
      Interpolacao: horizontal bilinear (renormalizando os pesos junto a costa),
      vertical linear entre os niveis, e conversao de temperatura de Kelvin para
      graus Celsius.

  mod_datetime.f90
      Calcula a data/hora do nome do arquivo de saida a partir de start_date mais
      o indice do timestep.

  mod_writer.f90
      Escreve os arquivos TXT no formato Fortran do usuario (ventos e correntes),
      com a formatacao de colunas exata.

  Apos a compilacao surgem arquivos intermediarios .o e .mod (objetos e modulos)
  e o executavel final "nc2txt". Os .o/.mod podem ser apagados com "make clean";
  o que voce executa e o "nc2txt".


3. COMPILACAO
-------------
A partir da raiz do projeto:

    make -C src/fortran

Isso usa o nf-config automaticamente para achar os caminhos do NetCDF e gera o
executavel:

    src/fortran/nc2txt

Para limpar os arquivos de compilacao (.o, .mod) e recompilar do zero:

    make -C src/fortran clean
    make -C src/fortran

Se "make" reclamar que nao encontra o netcdf.mod ou -lnetcdff, confirme que o
nf-config esta no PATH (passo 1).


4. CONFIGURACAO (arquivo config.nml)
------------------------------------
Edite o arquivo config.nml (formato NAMELIST Fortran). Exemplo comentado:

  &config
    input_dir   = './datain'                  ! pasta dos NetCDF de entrada
    grid_dir    = './dataout/googledrive_grid' ! pasta das grades e das saidas
    tmp_dir     = './dataout/tmp'              ! temporarios (nao usado no Fortran)

    grids       = 'EQ', 'NE', 'SE'            ! grades a processar

    ! --- Entrada atmosferica, dois modos ---
    ! Modo combinado: um unico arquivo com as 3 variaveis (u10m, v10m, tp2m)
    atm_file    = 'Eta03_BESM_2026060900_2D.new.nc'
    ! Modo separado: deixe atm_file = '' e informe um arquivo por variavel
    ! (variaveis uas, vas, tas). So e usado quando atm_file estiver vazio.
    atm_uas     = ''
    atm_vas     = ''
    atm_tas     = ''

    ! --- Entrada oceanica (um arquivo por variavel) ---
    uo_file     = '20260609.uo.new.nc'
    vo_file     = '20260609.vo.new.nc'
    thetao_file = '20260609.thetao.new.nc'
    so_file     = '20260609.so.new.nc'

    start_date  = '2026060900'   ! aaaammddhh do 1o timestep (define o nome dos arquivos)
    n_timesteps = 0              ! 0 = todos os timesteps; N = apenas os N primeiros
    fill_value  = -999.0         ! valor para pontos sem dado (terra/fora do dominio)

    ! 18 niveis verticais em metros (profundidade positiva)
    z_levels    = 0, 2, 4, 6, 8, 10, 15, 20, 25, 50, 100, 250, 500, 1000, 2000, 3000, 4000, 5000
  /

Observacoes:
  - Os caminhos sao relativos a pasta de onde voce roda o programa (a raiz do projeto).
  - Para um teste rapido, use n_timesteps = 1 (gera so o primeiro horario).


5. COMO RODAR
-------------
Sempre rode a partir da raiz do projeto (onde esta o config.nml):

    ./src/fortran/nc2txt config.nml

Se nenhum argumento for passado, ele procura "config.nml" na pasta atual.

O programa imprime o progresso, por exemplo:
    [winds] EQ t=  1 -> ./dataout/googledrive_grid/GRID_EQ/WINDS/winds_20260609_00.txt
    [currents] EQ t=  1 -> ./dataout/googledrive_grid/GRID_EQ/CURRENTS/currents_20260609_00.txt


6. VERIFICACAO DA SAIDA
-----------------------
  - Arquivo de ventos deve ter (Nx*Ny + 1) linhas (cabecalho + 1 por ponto da grade).
  - Arquivo de correntes deve ter (18*Nx*Ny + 1) linhas.
  - Conferir uma linha de agua (sem -999) tem valores fisicos plausiveis.

  Exemplo:
    wc -l dataout/googledrive_grid/GRID_EQ/CURRENTS/currents_20260609_00.txt


7. RECURSOS E DESEMPENHO
------------------------
  - Os arquivos de correntes sao grandes por especificacao (18 niveis x todos os
    pontos): cerca de 1,6 GB e ~17 milhoes de linhas por grade/timestep.
    A geracao completa (3 grades x 7 timesteps) ocupa ~36 GB. Garanta espaco em disco.
  - Memoria: baixa (pico em torno de 350 MB); o programa processa em fluxo.
  - Tempo: ordem de minutos por arquivo de correntes (depende do disco).


8. PROBLEMAS COMUNS
-------------------
  - "nf-config: command not found" ou erro de link com -lnetcdff: a biblioteca
    netCDF-Fortran nao esta instalada. Repita o passo 1.
  - "netcdf.mod not found" na compilacao: faltam os headers; instale o pacote
    -dev (libnetcdff-dev / netcdf-fortran-devel).
  - Saida com "****" no lugar de numeros: confirme fill_value = -999.0 no config.nml.
  - Disco cheio no meio da geracao: reduza n_timesteps ou rode uma grade por vez
    (ajuste a lista em "grids").
================================================================================
