Parâmetros de entrada

Os parâmetros de entrada permitem transformar valores dentro do código da sua estratégia (por exemplo, um período de retrospectiva ou um número máximo de posições compradas abertas) em controles que você define nas caixas de execução, sem editar o arquivo toda vez que quiser testar um novo número. A mesma estrutura params se aplica a Run backtest (Backtests), Bulk forward (AutoTrading / QuantCloud) e aos parâmetros do algoritmo no Chart forward test. O Test é descrito em Execução de código; as varreduras de várias execuções são tratadas em Otimização. Os params não são preenchidos em um Run simples.

Esta página cobre as duas metades desse fluxo:

• Declarar params no seu arquivo Python
• Ligar esses params às caixas de execução para poder defini-los, salvá-los e otimizá-los (veja também Predefinições de execução (.qcs))

---

Como funciona, em resumo

1. No seu arquivo de estratégia, você importa um objeto especial params e lê atributos dele (por exemplo, params.PERIOD).
2. O IDE analisa o seu código para descobrir esses nomes e os lista na caixa de execução (Test, bulk forward ou chart forward).
3. Você informa um tipo e um valor para cada nome na caixa de diálogo (ou define uma varredura ao otimizar).
4. Quando você inicia a execução, o mecanismo preenche params com os seus valores antes de o seu script ser executado, de modo que os valores estão disponíveis no instante em que o seu arquivo é importado.

As entradas são preenchidas nas caixas Run backtest, Bulk forward e Chart forward test. Elas não são preenchidas em um Run simples (/ws/run) — use valores padrão com hasattr se quiser que o mesmo arquivo funcione das duas formas. Veja Ciclo de vida da estratégia para saber quando os params ficam visíveis para os callbacks.

---

Declarando params na sua estratégia

Adicione uma única importação e referencie cada nome de parâmetro como atributo de params:

Algumas regras se aplicam:

• Escreva como from quantcraft.inputs import params. A expressão regular de descoberta também aceita as formas mais antigas from quantcraft.inputs_module import params e from ide.inputs_module import params para que os scripts existentes continuem funcionando — veja Referência — mas o código novo deve usar quantcraft.inputs. Deve ser a forma from … import params: import quantcraft.inputs as inp não é detectado, então a aba Script não aparecerá.
• O executor aplica os valores da caixa antes de o seu script de entrada ser carregado, o que é suficiente para from quantcraft.inputs import params no arquivo de estratégia.
• params é um único objeto “vivo”. Cada execução troca os valores por trás dele, então ele sempre mostra as entradas desta execução — inclusive em módulos auxiliares que o importaram durante uma execução forward anterior, e separadamente para execuções forward ativas ao mesmo tempo. Uma execução iniciada sem entradas vê um params vazio, nunca os valores da execução anterior.
• Cada nome de parâmetro deve ser um identificador Python válido (A–Z, a–z, 0–9, _, sem começar por dígito); qualquer outro é ignorado.
• Cada entrada deve incluir um token literal params.NAME no código-fonte para que o IDE possa descobri-la. O cliente procura por expressão regular params.<identificador>; nomes referenciados apenas via getattr(params, "NAME", default) não são descobertos e não aparecerão na aba Script. O getattr(params, "NAME", default) funciona em tempo de execução — basta manter um params.NAME literal na mesma linha para a descoberta.
• Você pode usar params.NAME em qualquer lugar do arquivo — no nível superior, dentro de on_init, dentro de on_bar etc. Cada referência única se torna uma entrada sobre a qual a caixa de diálogo perguntará.
• Não há esquema no próprio módulo — os nomes que você referencia são o esquema.

Evite (o formulário não listará o parâmetro):

Idiomas comuns:

Dica: leia o valor uma única vez para uma variável local/global para não pagar consultas de atributo a cada barra.

---

Ligando a caixa Test / backtest

Abra a caixa Test na barra de ferramentas do editor (o botão Test). Quando o seu arquivo declara entradas params.NAME, aparece uma aba Script com linhas de parâmetros e Optimize. O IDE já analisou o seu arquivo ativo em busca de referências params.NAME, então cada parâmetro usado aparece como uma linha.

Para cada linha você define:

Observações sobre as opções de Type:

• int / integer — números inteiros (por exemplo, 14); separadores de milhar são aceitos (1,000 → 1000).
• float / number — decimais (por exemplo, 0.5, 1e-3); vírgulas em números são removidas.
• bool / boolean — true / false, yes / no, y / n, on / off e 1 / 0 (qualquer combinação de maiúsculas e minúsculas). Qualquer outro valor interrompe a execução com invalid boolean: …. A caixa oferece True/False.
• str — texto livre, mantido como está (sem os espaços ao redor).

Ao iniciar o backtest, a caixa de diálogo empacota as suas linhas e as envia ao mecanismo. O mecanismo define os valores em params antes de o seu on_init() ser executado; assim:

Se um nome de parâmetro não tiver linha na caixa de diálogo (você removeu a entrada, ou seu arquivo referencia um nome totalmente novo que você ainda não definiu), params não terá esse atributo e uma leitura direta de params.NAME levantará AttributeError. Adicione a linha na caixa de diálogo e execute novamente — ou use o padrão hasattr + valor padrão else mostrado acima (que ainda inclui o token params.NAME para a descoberta).

Os valores da sua caixa de diálogo são lembrados entre as execuções, então você não precisa digitá-los de novo toda vez. Salve e recarregue conjuntos completos de parâmetros com as Predefinições de execução (.qcs).

---

Otimizando parâmetros

Na aba Script, ative Optimize para executar a sua estratégia várias vezes com diferentes combinações de parâmetros. Escolha Brute force ou Genetic:

Força bruta

Para cada linha de parâmetro, a caixa de diálogo adiciona colunas Step e Max quando faz sentido:

• int / float — defina uma grade discreta: valor inicial → passo → máximo.
• bool — tanto true quanto false são testados.
• str — mantido fixo (parâmetros de string não formam uma grade).

O mecanismo executa todas as combinações desses valores discretos e relata cada execução separadamente na visualização Test Results.

Útil para grades pequenas (alguns parâmetros com poucos valores cada). As combinações explodem rápido — mantenha o espaço de busca modesto.

Genético

Para espaços de busca maiores, mude para Genetic para deixar uma busca evolutiva encontrar boas combinações sem testar cada célula:

• Population size — número de combinações de parâmetros avaliadas a cada geração.
• Generations — quantas gerações executar (cada uma é uma população completa de backtests).
• Elitism — melhores indivíduos copiados sem alteração para a geração seguinte.
• Crossover rate (0–1) — chance de dois pais produzirem um filho misto.
• Mutation rate (0–1) — chance de um gene saltar para outro valor.
• Fitness metric — qual métrica otimizar (Sharpe, Sortino, retorno total etc.).
• Random seed (opcional) — reprodutibilidade da população e dos operadores.

Ambos os modos mostram o progresso ao vivo no painel de saída (uma barra de progresso no cabeçalho) e um botão Stop para encerrar uma execução longa.

Quando a otimização termina, a visualização Test Results mostra as execuções ordenadas pela sua métrica de aptidão, e você pode detalhar cada uma.

---

Dicas

• Os nomes são descobertos a partir do seu arquivo: se uma linha não aparecer, confira as suas referências params.NAME e se você importa params de quantcraft.inputs (os caminhos mais antigos quantcraft.inputs_module e ide.inputs_module também são reconhecidos, para scripts existentes).

• Mantenha os nomes em UPPER_SNAKE_CASE — por convenção, eles são lidos como constantes no seu código.

• Informe tipos adequados na caixa de diálogo para que a conversão faça o que você espera (por exemplo, não defina int para um valor como 0.5).

• Booleanos não diferenciam maiúsculas de minúsculas — True, true, 1, yes valem como verdadeiro.

• Use Optimize para buscas de parâmetros, não scripts do editor: a força bruta é exaustiva, a genética é para espaços maiores.

• O Run simples não preenche os params: ao clicar em Run, params não é preenchido. Use valores padrão com hasattr (com um token params.NAME literal) se quiser que o mesmo arquivo funcione tanto no Run quanto no Test:

  from quantcraft.inputs import params PERIOD = params.PERIOD if hasattr(params, "PERIOD") else 14

• As execuções forward usam as mesmas regras de descoberta — as caixas bulk forward e chart forward procuram params.NAME do mesmo modo que a caixa de backtest.