Guia Definitivo e à Prova de Falhas:
Construindo um Sistema Fármaco-Membrana com CHARMM-GUI para Simulações em GROMACS

Objetivo

Gerar um pacote de ficheiros completo e validado para a simulação de um fármaco numa membrana de POPC, utilizando as melhores práticas para garantir a reprodutibilidade e evitar erros comuns.

Pré-requisitos

1. Um ficheiro de coordenadas do seu fármaco com hidrogénios explícitos (ex: farmaco.mol2).
2. Acesso à internet para os servidores web.
3. Python 3 instalado para executar um script de correção essencial.

---

Módulo 1: Geração e Validação do Campo de Força do Fármaco

Objetivo: Obter os parâmetros de topologia e energia para o fármaco, utilizando o ecossistema CHARMM para garantir a compatibilidade com a membrana.

Passo 1.1: Gerar a Topologia com o Servidor CGenFF

• Ação: Aceda ao Servidor CGenFF/ParamChem.
• Ação: Carregue o seu ficheiro farmaco.mol2. O servidor irá processá-lo e gerar um ficheiro de stream (.str), que contém a topologia e os parâmetros.
• Ação: Faça o download e renomeie o ficheiro para farmaco_completo.str.
• Ponto Crítico (Validação): Abra o ficheiro .str e inspecione as "pontuações de penalidade" (penalty scores). Penalidades acima de 50 indicam uma analogia fraca e exigem cautela, pois podem levar a uma física imprecisa na simulação [75].

---

Módulo 2: Preparação e Divisão dos Ficheiros de Topologia

Objetivo: Converter os ficheiros gerados em formatos perfeitamente compatíveis com a interface do CHARMM-GUI, prevenindo os erros de leitura que encontramos.

Passo 2.1: Dividir o Ficheiro de Topologia e Parâmetros (.str)

A interface do CHARMM-GUI funciona de forma mais robusta quando a topologia e os parâmetros são fornecidos em ficheiros separados.

Ação 1: Criar o Ficheiro de Topologia (farmaco.rtf)

1. Abra o ficheiro farmaco_completo.str num editor de texto.
2. Copie todo o texto começando na primeira linha (a linha de título, ex: * Hybrid topology...) até à primeira linha que diz END.
3. Cole este conteúdo num novo ficheiro e salve-o como farmaco.rtf.

Justificativa (À Prova de Falhas): Este ficheiro deve incluir o cabeçalho antes da linha RESI para evitar o erro COULD NOT CONVERT STRING.

Ação 2: Criar o Ficheiro de Parâmetros (farmaco.prm)

1. Abra novamente o ficheiro farmaco_completo.str.
2. Copie todo o texto começando na linha que diz BONDS até ao final do ficheiro (incluindo o último END).
3. Cole este conteúdo num novo ficheiro e salve-o como farmaco.prm.

Passo 2.2: Corrigir o Ficheiro de Coordenadas (.pdb)

Esta é a etapa mais crítica para prevenir erros. O ficheiro PDB inicial (farmaco.pdb, convertido do .mol2) quase sempre tem incompatibilidades de nome de resíduo, nome de átomo e formatação de colunas. O script Python abaixo resolve todos estes problemas de uma só vez.

Ação 1: Crie um ficheiro Python (fix_pdb.py)

Crie um ficheiro chamado fix_pdb.py e cole o seguinte código:

import sys

def fix_pdb_for_charmm(pdb_file_in, str_file_in, pdb_file_out):
    """
    Reads atom names/order from a CHARMM .str file and coordinates
    from a PDB file, then writes a new, correctly formatted PDB file.
    """
    try:
        # --- 1. Read atom names and residue name from .str file ---
        with open(str_file_in, 'r') as f:
            str_lines = f.readlines()

        atom_names_from_str = []
        residue_name = None
        for line in str_lines:
            if line.strip().startswith('RESI'):
                residue_name = line.strip().split()[1]
            elif line.strip().startswith('ATOM'):
                atom_names_from_str.append(line.strip().split()[1])
            elif residue_name and atom_names_from_str and not line.strip().startswith('ATOM'):
                break # Stop after atom block
        
        if not residue_name or not atom_names_from_str:
            raise ValueError(f"Could not find RESI/ATOM definitions in {str_file_in}")

        # --- 2. Read coordinates from original .pdb file ---
        with open(pdb_file_in, 'r') as f:
            coords = [
                (float(line[30:38]), float(line[38:46]), float(line[46:54]))
                for line in f if line.startswith(('ATOM', 'HETATM'))
            ]

        # --- 3. Validate atom counts ---
        if len(atom_names_from_str) != len(coords):
            raise ValueError(
                f"Atom count mismatch: {str_file_in} has {len(atom_names_from_str)}, "
                f"but {pdb_file_in} has {len(coords)}."
            )

        # --- 4. Write the new, corrected .pdb file ---
        with open(pdb_file_out, 'w') as f_out:
            f_out.write("REMARK GENERATED BY CORRECTION SCRIPT FOR CHARMM-GUI\n")
            for i, atom_name in enumerate(atom_names_from_str):
                x, y, z = coords[i]
                serial = i + 1
                chain_id = "A"
                res_seq = 1
                element = atom_name[0]
                
                # Robust PDB format string to ensure every field is in the exact correct column.
                line = (
                    f"{'HETATM':<6}{serial:5d} {atom_name:^4s}{'':1s}{residue_name:3s} "
                    f"{chain_id:1s}{res_seq:4d}{'':4s}{x:8.3f}{y:8.3f}{z:8.3f}"
                    f"{1.00:6.2f}{0.00:6.2f}{'':10s}{element:>2s}\n"
                )
                f_out.write(line)
            f_out.write("END\n")

        print(f"Success! New file created: {pdb_file_out}")

    except Exception as e:
        print(f"An error occurred: {e}")

# --- Main execution ---
if __name__ == "__main__":
    original_pdb = "farmaco.pdb" # Mude para o nome do seu PDB original
    stream_file = "farmaco_completo.str" # O ficheiro .str completo do CGenFF
    corrected_pdb = "farmaco_corrigido.pdb"
    
    fix_pdb_for_charmm(original_pdb, stream_file, corrected_pdb)

Ação 2: Execute o script

1. Converta o seu farmaco.mol2 para farmaco.pdb usando um conversor como o Open Babel, se necessário.
2. No script, ajuste o nome original_pdb = "farmaco.pdb" para corresponder ao seu ficheiro.
3. Execute no terminal: python3 fix_pdb.py.

Resultado: Um novo ficheiro farmaco_corrigido.pdb será criado. Este ficheiro está agora 100% sincronizado com a sua topologia, prevenindo os erros de nome de resíduo, nome de átomo e formatação de colunas.

---

Módulo 3: O Passo a Passo no CHARMM-GUI

Com os três ficheiros validados (farmaco.rtf, farmaco.prm, farmaco_corrigido.pdb), o processo no CHARMM-GUI será direto e sem erros.

1. Início: Aceda ao CHARMM-GUI Membrane Builder. Selecione Protein/Membrane System.
2. Upload (PDB Info): Na seção Upload PDB File, carregue o seu ficheiro farmaco_corrigido.pdb. Clique em "Next Step".
3. Seleção de Cadeia (PDB Info): A sua molécula irá aparecer na lista. Marque a caixa de seleção ao lado dela e clique em "Next Step".
4. Upload da Topologia (Step 1):
   • Marque a opção Upload CHARMM top & par for hetero chain.
   • No campo Topology, carregue o ficheiro farmaco.rtf.
   • No campo Parameter, carregue o ficheiro farmaco.prm.
   • Clique em "Next Step".
5. Posicionamento (Step 2):
   • Orientation Options: Marque Use PDB Orientation.
   • Positioning Options: Marque Translate Molecule along Z axis e insira 35.
   • Clique em "Next Step".
6. Construção da Membrana (Step 3):
   • System Size Determination: Marque Numbers of lipid components.
   • Tabela de Lípidos: Expanda a secção PC (phosphatidylcholine) Lipids. Na linha do POPC, insira 64 para Upperleaflet e 64 para Lowerleaflet.
   • Clique no botão Show the system info (localizado acima da tabela). Espere o cálculo das dimensões.
   • Clique em "Next Step".
7. Adição de Íons (Step 4):
   • Component Building Options: No campo Concentration, insira 0.15.
   • Clique em Calculate Solvent Composition.
   • Clique em "Next Step".
8. Montagem dos Componentes (Step 4, parte 2): A página irá recarregar. Apenas clique em Next Step: Assemble Components.
9. Geração dos Ficheiros Finais (Step 5):
   • Force Field Options: Verifique se CHARMM36m está selecionado.
   • Input Generation Options: Marque apenas a caixa GROMACS.
   • Equilibration Options: Mantenha as opções padrão (NPT ensemble, 303.15 K).
   • Clique em "Next Step".
10. Download (Step 6):
    • A página final irá aparecer, confirmando o sucesso. Clique no botão download.tgz.

---

Conclusão

Ao seguir este guia, você terá gerado com sucesso um pacote .tgz contendo um sistema fármaco-membrana completo, robusto e pronto para a fase de equilibração no cluster COARACI. Este processo, embora detalhado, elimina as ambiguidades e previne proativamente os erros de formatação e compatibilidade, garantindo um ponto de partida fiável e reprodutível para as suas simulações de Dinâmica Molecular.