الصفحاتمعاملات الإدخال · 14 / 29

معاملات الإدخال

تتيح لك معاملات الإدخال تحويل القيم داخل شيفرة استراتيجيتك (مثل طول فترة الرجوع أو الحد الأقصى لعدد مراكز الشراء المفتوحة) إلى مفاتيح تضبطها من نوافذ التشغيل — دون تعديل الملف في كل مرة تريد فيها تجربة رقم جديد. ينطبق ربط params نفسه على Run backtest (الاختبارات الرجعية) وBulk forward (AutoTrading / QuantCloud) ومعاملات خوارزمية Chart forward test. ويُوصف Test في تشغيل الشيفرة؛ أما عمليات المسح المتعددة التشغيل فتُغطّى ضمن التحسين. ولا تُملأ params عند Run البسيط.

تغطي هذه الصفحة نصفي هذا التدفق:

التصريح عن params في ملف Python
ربط تلك params بنوافذ التشغيل لتتمكن من ضبطها وحفظها وتحسينها (راجع أيضًا إعدادات التشغيل المسبقة (.qcs))

كيف يعمل في لمحة

في ملف استراتيجيتك، تستورد كائنًا خاصًا params وتقرأ منه خصائص (مثل params.PERIOD).
تفحص بيئة التطوير شيفرتك لاكتشاف تلك الأسماء وتعرضها في نافذة التشغيل (Test أو bulk forward أو chart forward).
تُدخل نوعًا وقيمة لكل اسم في مربع الحوار (أو تعرّف مسحًا عند التحسين).
عند بدء التشغيل، يملأ المحرك params بقيمك قبل تشغيل نصّك، فتكون القيم متاحة لحظة استيراد ملفك.

تُملأ المدخلات في نوافذ Run backtest وBulk forward وChart forward test. ولا تُملأ في Run البسيط (/ws/run) — استخدم القيم الافتراضية بـ hasattr إن أردت أن يعمل الملف نفسه بالطريقتين. راجع دورة حياة الاستراتيجية لمعرفة متى تكون params مرئية لدوال الاستدعاء.

التصريح عن params في استراتيجيتك

أضف استيرادًا واحدًا وأشر إلى كل اسم معامل كخاصية على params:

from quantcraft.inputs import params

PERIOD = params.PERIOD if hasattr(params, "PERIOD") else 14
MAX_OPEN_LONGS = params.MAX_OPEN_LONGS if hasattr(params, "MAX_OPEN_LONGS") else 3
USE_FILTER = params.USE_FILTER if hasattr(params, "USE_FILTER") else True
LABEL = params.LABEL if hasattr(params, "LABEL") else "default"

تنطبق بعض القواعد:

اكتبه بصيغة from quantcraft.inputs import params. يقبل التعبير النمطي للاكتشاف أيضًا الصيغتين الأقدم from quantcraft.inputs_module import params و**from ide.inputs_module import params** لتستمر النصوص الحالية في العمل — راجع المرجع — لكن الشيفرة الجديدة يجب أن تستخدم quantcraft.inputs. ويجب أن تكون بصيغة from … import params: فصيغة import quantcraft.inputs as inp لا تُكتشف، لذا لن تظهر علامة تبويب Script.
يطبّق المشغّل قيم النافذة قبل تحميل نص الدخول، وهذا كافٍ لـ from quantcraft.inputs import params في ملف الاستراتيجية.
params كائن واحد «حي». يبدّل كل تشغيل القيم الكامنة خلفه، لذا يعرض دائمًا مدخلات هذا التشغيل — بما في ذلك في الوحدات المساعدة التي استوردته أثناء تشغيل أمامي سابق، وبشكل منفصل لعمليات التشغيل الأمامي الجارية في آن واحد. والتشغيل الذي يبدأ دون مدخلات يرى params فارغًا، ولا يرى قيم التشغيل السابق أبدًا.
يجب أن يكون كل اسم معامل معرّف Python صالحًا (A–Z وa–z و0–9 و_، ولا يبدأ برقم)؛ وأي شيء آخر يُتجاهل.
يجب أن يتضمن كل مدخل رمز params.NAME حرفيًا في المصدر ليتمكن IDE من اكتشافه. يطابق العميل params.<معرّف> بتعبير نمطي؛ أما الأسماء المشار إليها عبر getattr(params, "NAME", default) فقط فـلا تُكتشف ولن تظهر في علامة تبويب Script. ويعمل getattr(params, "NAME", default) وقت التشغيل — فقط أبقِ params.NAME حرفيًا في السطر نفسه للاكتشاف.
يمكنك استخدام params.NAME في أي مكان في الملف — على المستوى الأعلى أو داخل on_init أو داخل on_bar وهكذا. يصبح كل إشارة فريدة مدخلًا سيسألك عنه مربع الحوار.
لا يوجد مخطط في الوحدة نفسها — فالأسماء التي تشير إليها هي المخطط.

تجنّب (لن يدرج النموذج المعامل):

MA_PERIOD = getattr(params, "MA_PERIOD", 24)  # no params.MA_PERIOD token
PERIOD = 14  # no params reference

أنماط شائعة:

def on_init():
    global lookback
    lookback = int(params.PERIOD)

def on_bar(bar_index, bar, fundamentals=None, symbol=None):
    if bar.bars_back < lookback:
        return
    ...

نصيحة: اقرأ القيمة مرة واحدة في متغير محلي/عام حتى لا تدفع كلفة البحث عن الخاصية في كل عمود.

ربط نافذة Test / الاختبار الرجعي

افتح مربع حوار Test من شريط أدوات المحرر (زر Test). عندما يصرّح ملفك عن مدخلات params.NAME، تظهر علامة تبويب Script تضم صفوف المعاملات وOptimize. وقد فحصت بيئة التطوير ملفك النشط بالفعل بحثًا عن إشارات params.NAME، فيظهر كل معامل استخدمته كصف.

لكل صف تضبط:

العمود	ما تُدخله
Parameter	الاسم (للقراءة فقط — يأتي من شيفرتك).
Type	واحد من `int` و`float` و`str` و`bool` (وتُقبل أيضًا الأسماء المستعارة `integer` و`number` و`boolean` عند النقل).
Value	القيمة المراد استخدامها في التشغيل.

ملاحظات بشأن خيارات Type:

int / integer — أعداد صحيحة (مثل 14)؛ وفواصل الآلاف مقبولة (1,000 ← 1000).
float / number — أعداد عشرية (مثل 0.5 و1e-3)؛ وتُزال الفواصل من الأرقام.
bool / boolean — true / false وyes / no وy / n وon / off و1 / 0 (بأي حالة أحرف). وأي شيء آخر يوقف التشغيل برسالة invalid boolean: …. وتعرض النافذة True/False.
str — نص حر، يُحفظ كما هو (مع إزالة المسافات المحيطة).

عند بدء الاختبار الرجعي، يجمع مربع الحوار صفوفك ويرسلها إلى المحرك. يضبط المحرك القيم على params قبل تشغيل on_init() لديك، بحيث:

from quantcraft.inputs import params
PERIOD = params.PERIOD   # <- already filled by the time this line executes

إذا لم يكن لاسم معامل صف في مربع الحوار (حذفت الإدخال، أو يشير ملفك إلى اسم جديد تمامًا لم تضبطه بعد)، فلن تحتوي params على تلك الخاصية وسيُطلق القراءة المباشرة لـ params.NAME الاستثناء AttributeError. أضف الصف في مربع الحوار وأعد التشغيل — أو استخدم نمط hasattr + القيمة الافتراضية else المعروض أعلاه (الذي لا يزال يتضمن رمز params.NAME للاكتشاف).

تُحفظ قيم مربع الحوار بين عمليات التشغيل، فلا حاجة إلى إعادة كتابتها في كل مرة. احفظ مجموعات المعاملات الكاملة وأعد تحميلها بـإعدادات التشغيل المسبقة (.qcs).

تحسين المعاملات

في علامة تبويب Script، فعّل Optimize لتشغيل استراتيجيتك مرات عديدة بتركيبات معاملات مختلفة. اختر Brute force أو Genetic:

القوة الغاشمة

لكل صف معامل، يضيف مربع الحوار عمودي Step وMax حيث يكون ذلك منطقيًا:

int / float — تعرّف شبكة منفصلة: القيمة الابتدائية ← الخطوة ← الحد الأقصى.
bool — تُجرَّب true وfalse معًا.
str — تبقى ثابتة (معاملات السلاسل لا تشكّل شبكة).

يشغّل المحرك كل تركيبة من تلك القيم المنفصلة ويبلّغ عن كل تشغيل على حدة في عرض Test Results.

مفيد للشبكات الصغيرة (حفنة من المعاملات بقيم قليلة لكل منها). تتضخم التركيبات بسرعة — أبقِ فضاء البحث متواضعًا.

الجيني

لفضاءات البحث الأكبر، بدّل إلى Genetic ليعثر بحث تطوري على تركيبات جيدة دون تجربة كل خلية:

Population size — عدد تركيبات المعاملات المقيَّمة في كل جيل.
Generations — عدد الأجيال المراد تشغيلها (كل منها مجموعة كاملة من الاختبارات الرجعية).
Elitism — أفضل الأفراد يُنسخون دون تغيير إلى الجيل التالي.
Crossover rate (0–1) — احتمال أن ينتج والدان طفلًا مختلطًا.
Mutation rate (0–1) — احتمال أن يقفز جين إلى قيمة أخرى.
Fitness metric — المقياس المراد تحسينه (Sharpe أو Sortino أو العائد الإجمالي وغيرها).
Random seed (اختياري) — قابلية إعادة إنتاج المجموعة والمُشغِّلات.

يعرض الوضعان التقدّم المباشر في لوحة المخرجات (شريط تقدّم في الترويسة) وزر Stop لإنهاء تشغيل طويل.

عند انتهاء التحسين، يعرض عرض Test Results عمليات التشغيل مرتبة حسب مقياس اللياقة لديك، ويمكنك التعمّق في كل منها.

نصائح

تُكتشف الأسماء من ملفك: إذا لم يظهر صف، فتحقق من إشارات params.NAME ومن أنك تستورد params من quantcraft.inputs (وتُطابَق أيضًا المسارات الأقدم quantcraft.inputs_module و**ide.inputs_module** للنصوص الحالية).
أبقِ الأسماء بصيغة UPPER_SNAKE_CASE — فبحسب العرف تُقرأ كثوابت في شيفرتك.
حدّد أنواعًا مناسبة في مربع الحوار ليفعل التحويل ما تتوقعه (مثلًا لا تضبط int لقيمة مثل 0.5).
القيم المنطقية غير حساسة لحالة الأحرف — True وtrue و1 وyes كلها تُقيَّم صحيحة.
استخدم Optimize لعمليات البحث عن المعاملات، لا نصوص المحرر: القوة الغاشمة شاملة، والجينية للفضاءات الأكبر.
Run البسيط لا يملأ params: عند نقر Run، لا تُملأ params. استخدم القيم الافتراضية بـ hasattr (مع رمز params.NAME حرفي) إن أردت أن يعمل الملف نفسه مع Run وTest معًا:

from quantcraft.inputs import params PERIOD = params.PERIOD if hasattr(params, "PERIOD") else 14
تستخدم عمليات التشغيل الأمامي قواعد الاكتشاف نفسها — تفحص نافذتا bulk forward وchart forward بحثًا عن params.NAME بالطريقة نفسها التي يفعلها مربع حوار الاختبار الرجعي.

7 دقائق للقراءةاقترح تعديلًا ↗