re-commit

test/utils/README.md

@@ -0,0 +1,116 @@
+# 🐳 Run Docker & Qlib
+---
+
+## 📄 Description
+This guide explains how to run the Qlib Docker test file located at `test/utils/test_env.py` in the RD-Agent repository.
+
+---
+
+## 🚀 Running Instructions
+
+### 1. Install the required Python libraries
+- Ensure that the `docker` Python library is installed:
+    ```sh
+    pip install docker
+    ```
+
+### 2. Run the test script
+- Execute the test script to verify the Docker environment setup:
+    ```sh
+    python test/utils/test_env.py
+    ```
+
+### Troubleshooting
+- **PermissionError: [Errno 13] Permission denied.**
+    > This error occurs when the current user does not have the necessary permissions to access the Docker socket. To resolve this issue, follow these steps:
+
+1. **Add the current user to the `docker` group**
+Docker requires root or `docker` group user permissions to access the Docker socket. Add the current user to the `docker` group:
+    ```sh
+    sudo usermod -aG docker $USER
+    ```
+
+2. **Refresh group changes**
+To apply the group changes, log out and log back in, or use the following command:
+    ```sh
+    newgrp docker
+    ```
+
+3. **Verify Docker access**
+Run the following command to ensure that Docker can be accessed:
+    ```sh
+    docker run hello-world
+    ```
+
+4. **Rerun the test script**
+    After completing these steps, rerun the test script:
+    ```sh
+    python test/utils/test_env.py
+    ```
+---
+## 🛠️ Detailed Qlib Docker Function Framework
+
+Here, we provide an overview of the specific functions within the Qlib Docker framework, their purposes, and examples of how to call them.
+
+### QTDockerEnv Class in `env.py`
+
+The `QTDockerEnv` class is responsible for setting up and running Docker environments for Qlib experiments. 
+
+#### Methods:
+
+1. **prepare()**
+   - **Purpose**: Prepares the Docker environment for running experiments. This includes building the Docker image if necessary.
+   - **Example**:
+     ```python
+     qtde = QTDockerEnv()
+     qtde.prepare()
+     ```
+
+2. **run(local_path: str, entry: str) -> str**
+   - **Purpose**: Runs a specified entry point (e.g., a configuration file) in the prepared Docker environment.
+   - **Parameters**:
+     - `local_path`: Path to the local directory to mount into the Docker container.
+     - `entry`: Command or entry point to run inside the Docker container.
+   - **Returns**: The stdout output from the Docker container.
+   - **Example**:
+     ```python
+     result = qtde.run(local_path="/path/to/env_tpl", entry="qrun conf.yaml")
+     ```
+---
+### 📊 Expected Output
+
+Upon successful execution, the test script will produce analysis results of benchmark returns and various risk metrics. The expected output should be similar to:
+
+```
+'The following are analysis results of benchmark return (1 day).'
+risk
+mean               0.000477
+std                0.012295
+annualized_return  0.113561
+information_ratio  0.598699
+max_drawdown      -0.370479
+
+'The following are analysis results of the excess return without cost (1 day).'
+risk
+mean               0.000530
+std                0.005718
+annualized_return  0.126029
+information_ratio  1.428574
+max_drawdown      -0.072310
+
+'The following are analysis results of the excess return with cost (1 day).'
+risk
+mean               0.000339
+std                0.005717
+annualized_return  0.080654
+information_ratio  0.914486
+max_drawdown      -0.086083
+
+'The following are analysis results of indicators (1 day).'
+value
+ffr    1.0
+pa     0.0
+pos    0.0
+```
+
+By following these steps and using the provided functions, you should be able to run the Qlib Docker tests and obtain the expected analysis results.

test/utils/test_env.py

@@ -23,18 +23,17 @@ class EnvUtils(unittest.TestCase):
 
     # NOTE: Since I don't know the exact environment in which it will be used, here's just an example.
     # NOTE: Because you need to download the data during the prepare process. So you need to have pyqlib in your environment.
-    # def test_local(self):
-    #     local_conf = LocalConf(
-    #         py_bin="/home/v-linlanglv/miniconda3/envs/RD-Agent-310/bin",
-    #         default_entry="qrun conf.yaml",
-    #     )
-    #     qle = LocalEnv(conf=local_conf)
-    #     qle.prepare()
-    #     exe_path = str(DIRNAME / "env_tpl")
-    #     conf_path = str(DIRNAME / "env_tpl" / "conf.yaml") 
-    #     qle.run(entry="qrun " + conf_path, local_path=exe_path)
-    #     mlrun_p = DIRNAME / "env_tpl" / "mlruns" 
-    #     self.assertTrue(mlrun_p.exists(), f"Expected output file {mlrun_p} not found")
+    def test_local(self):
+        local_conf = LocalConf(
+            py_bin="/home/v-linlanglv/miniconda3/envs/RD-Agent-310/bin",
+            default_entry="qrun conf.yaml",
+        )
+        qle = LocalEnv(conf=local_conf)
+        qle.prepare()
+        conf_path = str(DIRNAME / "env_tpl" / "conf.yaml") 
+        qle.run(entry="qrun " + conf_path)
+        mlrun_p = DIRNAME / "env_tpl" / "mlruns" 
+        self.assertTrue(mlrun_p.exists(), f"Expected output file {mlrun_p} not found")
 
     def test_docker(self):
         """
@@ -51,7 +50,8 @@ class EnvUtils(unittest.TestCase):
         self.assertTrue(mlrun_p.exists(), f"Expected output file {mlrun_p} not found")
 
         # read experiment
-        result = qtde.run(local_path=str(DIRNAME / "env_tpl"), entry="python read_exp.py")
+        result = qtde.run(local_path=str(DIRNAME / "env_tpl"), entry="python read_exp_res.py")
+        print("here")
         print(result)
 
 

test/utils/test_env2.py

@@ -0,0 +1,38 @@
+import os
+import sys
+import unittest
+from pathlib import Path
+sys.path.append(str(Path(__file__).resolve().parent.parent))
+from rdagent.utils.env import QTDockerEnv, LocalEnv, LocalConf
+import shutil
+
+
+DIRNAME = Path(__file__).absolute().resolve().parent
+
+
+class EnvUtils(unittest.TestCase):
+    def setUp(self):
+        pass
+    
+    def test_docker(self):
+        """
+        We will mount `env_tpl` into the docker image.
+        And run the docker image with `qrun conf.yaml`
+        """
+        qtde = QTDockerEnv()
+        qtde.prepare()
+        qtde.prepare()  # you can prepare for multiple times. It is expected to handle it correctly
+        # the stdout are returned as result
+        result = qtde.run(local_path=str(DIRNAME / "env_tpl"), entry="qrun conf2.yaml")
+        
+        mlrun_p = DIRNAME / "env_tpl" / "mlruns" 
+        self.assertTrue(mlrun_p.exists(), f"Expected output file {mlrun_p} not found")
+
+        # read experiment
+        result = qtde.run(local_path=str(DIRNAME / "env_tpl"), entry="python read_exp_res.py")
+        print("here")
+        # print(result)
+
+
+if __name__ == "__main__":
+    unittest.main()