Otimizar um cBot¶

O comando optimize explora diferentes valores dos parâmetros de um cBot para encontrar as combinações com os melhores resultados de acordo com os critérios escolhidos. Executa a mesma pesquisa genética ou em grelha que a aplicação cTrader para desktop, mas a partir do terminal e através de um ficheiro JSON com os parâmetros. É o equivalente, para a otimização, ao comando de testes de verificação.

Âmbito ¶

O comando optimize otimiza os parâmetros dos cBots. Os indicadores e os plugins têm os seus próprios comandos (indicator calculate, indicator history, create, build) e não estão incluídos na otimização.

Pré-requisitos ¶

• Ter o cTrader CLI instalado e conseguir iniciar sessão.
• O cBot deve estar exportado como ficheiro .algo e compilado para .NET 8.
• Um ficheiro de parâmetros que defina os parâmetros a explorar.

O comando optimize ¶

ctrader-cli optimize <path-to-algo-file> --params=<path-to-params-file> [options]

O caminho para o ficheiro .algo é o primeiro argumento. A opção --params é obrigatória. O intervalo de tempo de base tem de ser definido através de --timeframe ou no ficheiro de parâmetros. Se não for definido em nenhum dos dois, o comando termina com um erro.

Opções de otimização ¶

A única opção obrigatória é --params. As opções facultativas mais comuns, utilizadas nos exemplos seguintes, são --timeframe, --method, --criteria, --optres e --passes-dir.

Convém conhecer algumas opções antes de começar:

• --method – genetic (predefinido) ou grid. Escolha grid se houver poucas combinações de parâmetros e quiser testar todas. Escolha genetic se houver muitas combinações e uma pesquisa orientada puder ser mais rápida.
• --cores – número de processos de trabalho em paralelo que executam os testes de verificação de cada execução de otimização. Cada processo utiliza uma thread da CPU, pelo que a otimização ocupa aproximadamente tantas threads quantas as indicadas neste valor. São aceites números inteiros iguais ou superiores a 1. Por predefinição, o valor corresponde a metade do número de processadores, mais um. Reduza o valor num VPS de pequena dimensão para deixar recursos disponíveis para outras tarefas. Numa máquina dedicada, pode aumentá-lo para distribuir a pesquisa genética por mais threads.
• --auto-select-best – seleciona automaticamente a melhor execução no final da otimização, para que o ficheiro .cbotset com os parâmetros de melhor desempenho fique disponível sem passos adicionais.

O ficheiro de parâmetros ¶

O ficheiro indicado através de --params é um objeto JSON que contém uma matriz parameters. Tem a mesma estrutura do ficheiro exportado pela interface de otimização da aplicação cTrader para desktop, pelo que pode utilizar diretamente um ficheiro exportado dessa aplicação.

{
  "parameters": [
    { "Name": "SlowPeriods",  "Optimize": true, "Min": "5",  "Max": "50", "Step": "5" },
    { "Name": "StopLossPips", "Optimize": true, "Min": "10", "Max": "60", "Step": "5" },
    { "Name": "MAType",       "Optimize": true, "Values": ["0", "1", "2"] },
    { "Name": "MySymbol",     "Optimize": true, "Values": ["EURUSD", "GBPUSD"] }
  ]
}

Regras dos campos ¶

• O campo Name é obrigatório e tem de corresponder ao nome de uma propriedade do cBot. Execute ctrader-cli metadata <path-to-algo> para consultar os nomes das propriedades disponíveis. Se um nome não constar dos metadados do cBot, essa situação é registada e o parâmetro é ignorado. A otimização prossegue com os restantes parâmetros.
• Se Optimize tiver o valor true, o parâmetro é incluído na pesquisa. Se tiver o valor false, o parâmetro permanece fixo.
• Para os parâmetros definidos por intervalos, como números inteiros ou de vírgula flutuante, são necessários os campos Min, Max e Step se o parâmetro tiver de variar.
• Para os parâmetros com valores discretos, como enumerações ou símbolos, é necessária uma matriz Values não vazia se o parâmetro tiver de variar.
• O campo ParameterType é facultativo. Se for omitido, o tipo é determinado através dos metadados do cBot, por correspondência com Name.

Fixar um parâmetro num único valor ¶

Para manter um parâmetro fixo, inclua-o com Optimize: false e o respetivo Value:

{ "Name": "MAType",      "Value": "1", "Optimize": false },
{ "Name": "FastPeriods", "Value": "5", "Optimize": false }

Otimizar o intervalo de tempo principal ¶

O comando optimize permite explorar diferentes intervalos de tempo principais, além dos parâmetros do cBot. O intervalo de tempo principal pode ser definido de duas formas, tendo --timeframe prioridade.

• --timeframe <tf> – um único valor fixa o intervalo de tempo principal; vários valores separados por vírgulas permitem explorar diferentes intervalos de tempo.
• Ficheiro de parâmetros – um ficheiro exportado da aplicação para desktop já inclui um parâmetro sintético de intervalo de tempo para este efeito.

O intervalo de tempo de base dos dados corresponde ao valor único, ao valor fixo ou ao menor dos valores explorados.

Compatibilidade entre intervalos de tempo e modos de dados ¶

Os intervalos de tempo principais que sejam explorados ou fixados têm de ser compatíveis com o --data-mode escolhido.

Critérios ¶

Cada elemento de --criteria associa uma métrica de desempenho a uma direção max ou min, por exemplo NetProfit:max. A tabela seguinte apresenta todos os nomes de métricas suportados e o que medem.

Para maximizar o lucro líquido e, ao mesmo tempo, minimizar a maior queda do capital:

--criteria="NetProfit:max,MaxEquityDrawdownPercentages:min"

Para definir uma classificação personalizada, utilize --fitness. O método GetFitness do cBot devolve uma pontuação; a otimização mantém as execuções com as pontuações mais elevadas. --fitness e --criteria são mutuamente exclusivos: especifique apenas um deles.

Opções do contexto de teste ¶

optimize reutiliza as opções do contexto de teste de backtest. A tabela seguinte apresenta as opções aceites pela CLI atual, a respetiva função e, quando relevante, as diferenças entre os dois comandos.

Exemplo ¶

ctrader-cli optimize "C:/test/Sample Trend cBot.algo" \
  --params=C:/test/optimize-params.json \
  --account=1234567 --symbol=EURUSD --timeframe=h1,h2 \
  --start="01/01/2025" --end="01/02/2025" \
  --balance=100000 --data-mode=open --commission=30 --spread=2 \
  --method=grid \
  --criteria="NetProfit:max,MaxEquityDrawdownPercentages:min" \
  --auto-select-best \
  --optres=C:/test/result.optres \
  --passes-dir=C:/test/result-passes \
  --ctid=letstrade --pwd-file=C:/test/password.pwd

Saída ¶

Durante a execução, optimize apresenta continuamente o progresso no terminal:

Progress | Loading EURUSD, h1 | 42.00 % |
Progress | Optimization | 37.50 % |

• Resumo – no final da otimização, o cTrader CLI apresenta no terminal um resumo com o número total de execuções, o tempo decorrido e a melhor execução com as respetivas estatísticas.
• Ficheiro de resultados – se especificar --optres, o cTrader CLI guarda os resultados completos num ficheiro JSON .optres que lista todas as execuções. Este ficheiro utiliza o mesmo formato dos resultados de otimização da aplicação para desktop, pelo que pode abri-lo ou importá-lo na respetiva interface de otimização.
• Relatórios por execução – se especificar --passes-dir, o cTrader CLI guarda os relatórios de cada execução nessa diretoria, com uma subpasta por execução que contém ficheiros .html, .txt, .json e .cbotset. O ficheiro .cbotset apresenta os valores exatos dos parâmetros utilizados nessa execução.

Se não especificar --optres nem --passes-dir, a otimização termina e apresenta apenas o resumo.

Verificar se a otimização foi aplicada corretamente ¶

Após a execução, verifique se a pesquisa percorreu os parâmetros pretendidos.

1. Abra um ficheiro .cbotset de uma execução em --passes-dir e confirme que os parâmetros otimizados variam entre execuções, enquanto os parâmetros fixos ou omitidos se mantêm inalterados.
2. Se tiver explorado vários intervalos de tempo, verifique o valor Chart.Period no ficheiro .cbotset de cada execução. Deve corresponder a um dos intervalos de tempo selecionados.
3. Abra o ficheiro .optres ou importe-o na interface de otimização da aplicação para desktop para analisar a configuração e todas as execuções em conjunto.

Validação e erros comuns ¶

Cada linha da tabela seguinte apresenta um sintoma, a causa provável, o código de saída devolvido pelo cTrader CLI em caso de falha e a ação a tomar. O cTrader CLI devolve um código de saída diferente de zero para todos os erros de validação. Assim, um script pode interromper-se no primeiro erro sem ter de interpretar a mensagem.

Na tabela, o código de saída corresponde ao valor devolvido pelo cTrader CLI à shell. Os códigos numéricos exatos não estão publicados. Por isso, non-zero indica uma falha sem um código específico publicado, enquanto unknown indica um erro interno que exige mudar de versão ou contactar o suporte.