.. image:: https://raw.githubusercontent.com/mars-project/mars/master/docs/source/images/mars-logo-title.png

|PyPI版本| |文档| |构建| |覆盖率| |质量| |许可证|

Mars 是一个基于张量的大规模数据计算统一框架，能够扩展 NumPy、Pandas、scikit-learn 等多种库的功能。

文档, 中文文档

安装

Mars 的安装非常简单，只需执行以下命令：

.. code-block:: bash

pip install pymars

开发者安装

如果您希望为 Mars 贡献代码，可以按照以下步骤进行开发环境的安装：

.. code-block:: bash

    git clone https://github.com/mars-project/mars.git
    cd mars
    pip install -e ".[dev]"

更多关于 Mars 安装的详细信息，请参阅 Mars 文档中的 `安装 <https://mars-project.readthedocs.io/en/latest/installation/index.html>`_ 部分。


架构概览
--------

.. image:: https://raw.githubusercontent.com/mars-project/mars/master/docs/source/images/architecture.png


快速入门
--------

在本地启动一个新的运行时：

.. code-block:: python

    >>> import mars
    >>> mars.new_session()

或者连接到已初始化的 Mars 集群：

.. code-block:: python

    >>> import mars
    >>> mars.new_session('http://<web_ip>:<ui_port>')


Mars 张量
----------

Mars 张量提供了与 NumPy 类似的熟悉接口。

+-----------------------------------------------+-----------------------------------------------+
| **NumPy**                                     | **Mars 张量**                               |
+-----------------------------------------------+-----------------------------------------------+
|.. code-block:: python                         |.. code-block:: python                         |
|                                               |                                               |
|    import numpy as np                         |    import mars.tensor as mt                   |
|    N = 200_000_000                            |    N = 200_000_000                            |
|    a = np.random.uniform(-1, 1, size=(N, 2))  |    a = mt.random.uniform(-1, 1, size=(N, 2))  |
|    print((np.linalg.norm(a, axis=1) < 1)      |    print(((mt.linalg.norm(a, axis=1) < 1)     |
|          .sum() * 4 / N)                      |            .sum() * 4 / N).execute())         |
|                                               |                                               |
+-----------------------------------------------+-----------------------------------------------+
|.. code-block::                                |.. code-block::                                |
|                                               |                                               |
|    3.14174502                                 |     3.14161908                                |
|    CPU times: user 11.6 s, sys: 8.22 s,       |     CPU times: user 966 ms, sys: 544 ms,      |
|               total: 19.9 s                   |                total: 1.51 s                  |
|    Wall time: 22.5 s                          |     Wall time: 3.77 s                         |
|                                               |                                               |
+-----------------------------------------------+-----------------------------------------------+

Mars 可以充分利用多核资源，即使在笔记本电脑上也能显著提升性能，并且在分布式环境中表现更优。


Mars DataFrame
--------------

Mars DataFrame 提供了与 Pandas 类似的熟悉接口。

+-----------------------------------------+-----------------------------------------+
| **Pandas**                              | **Mars DataFrame**                      |
+-----------------------------------------+-----------------------------------------+
|.. code-block:: python                   |.. code-block:: python                   |
|                                         |                                         |
|    import numpy as np                   |    import mars.tensor as mt             |
|    import pandas as pd                  |    import mars.dataframe as md          |
|    df = pd.DataFrame(                   |    df = md.DataFrame(                   |
|        np.random.rand(100000000, 4),    |        mt.random.rand(100000000, 4),    |
|        columns=list('abcd'))            |        columns=list('abcd'))            |
|    print(df.sum())                      |    print(df.sum().execute())            |
|                                         |                                         |
+-----------------------------------------+-----------------------------------------+
|.. code-block::                          |.. code-block::                          |
|                                         |                                         |
|    CPU times: user 10.9 s, sys: 2.69 s, |    CPU times: user 1.21 s, sys: 212 ms, |
|               total: 13.6 s             |               total: 1.42 s             |
|    Wall time: 11 s                      |    Wall time: 2.75 s                    |
+-----------------------------------------+-----------------------------------------+


Mars Learn
----------

Mars Learn 提供了与 scikit-learn 类似的熟悉接口。

+---------------------------------------------+----------------------------------------------------+
| **Scikit-learn**                            | **Mars learn**                                     |
+---------------------------------------------+----------------------------------------------------+
|.. code-block:: python                       |.. code-block:: python                              |
|                                             |                                                    |
|    from sklearn.datasets import make_blobs  |    from mars.learn.datasets import make_blobs      |
|    from sklearn.decomposition import PCA    |    from mars.learn.decomposition import PCA        |
|    X, y = make_blobs(                       |    X, y = make_blobs(                              |
|        n_samples=100000000, n_features=3,   |        n_samples=100000000, n_features=3,          |
|        centers=[[3, 3, 3], [0, 0, 0],       |        centers=[[3, 3, 3], [0, 0, 0],              |
|                 [1, 1, 1], [2, 2, 2]],      |                  [1, 1, 1], [2, 2, 2]],            |
|        cluster_std=[0.2, 0.1, 0.2, 0.2],    |        cluster_std=[0.2, 0.1, 0.2, 0.2],           |
|        random_state=9)                      |        random_state=9)                             |
|    pca = PCA(n_components=3)                |    pca = PCA(n_components=3)                       |
|    pca.fit(X)                               |    pca.fit(X)                                      |
|    print(pca.explained_variance_ratio_)     |    print(pca.explained_variance_ratio_)            |
|    print(pca.explained_variance_)           |    print(pca.explained_variance_)                  |
|                                             |                                                    |
+---------------------------------------------+----------------------------------------------------+

Mars learn 还与许多库集成：

- `TensorFlow <https://mars-project.readthedocs.io//en/latest/user_guide/learn/tensorflow.html>`_
- `PyTorch <https://mars-project.readthedocs.io/en/latest/user_guide/learn/pytorch.html>`_
- `XGBoost <https://mars-project.readthedocs.io/en/latest/user_guide/learn/xgboost.html>`_
- `LightGBM <https://mars-project.readthedocs.io/en/latest/user_guide/learn/lightgbm.html>`_
- `Joblib <https://mars-project.readthedocs.io/en/latest/user_guide/learn/joblib.html>`_
- `Statsmodels <https://mars-project.readthedocs.io/en/latest/user_guide/learn/statsmodels.html>`_

Mars remote
-----------

Mars remote 允许用户并行执行函数。

+-------------------------------------------+--------------------------------------------+
| **普通函数调用**                          | **Mars remote**                            |
+-------------------------------------------+--------------------------------------------+
|.. code-block:: python                     |.. code-block:: python                      |
|                                           |                                            |
|    import numpy as np                     |    import numpy as np                      |
|                                           |    import mars.remote as mr                |
|                                           |                                            |
|    def calc_chunk(n, i):                  |    def calc_chunk(n, i):                   |
|        rs = np.random.RandomState(i)      |        rs = np.random.RandomState(i)       |
|        a = rs.uniform(-1, 1, size=(n, 2)) |        a = rs.uniform(-1, 1, size=(n, 2))  |
|        d = np.linalg.norm(a, axis=1)      |        d = np.linalg.norm(a, axis=1)       |
|        return (d < 1).sum()               |        return (d < 1).sum()                |
|                                           |                                            |
|    def calc_pi(fs, N):                    |    def calc_pi(fs, N):                     |
|        return sum(fs) * 4 / N             |        return sum(fs) * 4 / N              |
|                                           |                                            |
|    N = 200_000_000                        |    N = 200_000_000                         |
|    n = 10_000_000                         |    n = 10_000_000                          |
|                                           |                                            |
|    fs = [calc_chunk(n, i)                 |    fs = [mr.spawn(calc_chunk, args=(n, i)) |
|          for i in range(N // n)]          |          for i in range(N // n)]           |
|    pi = calc_pi(fs, N)                    |    pi = mr.spawn(calc_pi, args=(fs, N))    |
|    print(pi)                              |    print(pi.execute().fetch())             |
|                                           |                                            |
+-------------------------------------------+--------------------------------------------+
|.. code-block::                            |.. code-block::                             |
|                                           |                                            |
|    3.1416312                              |    3.1416312                               |
|    CPU times: user 32.2 s, sys: 4.86 s,   |    CPU times: user 616 ms, sys: 307 ms,    |
|               total: 37.1 s               |               total: 923 ms                |
|    Wall time: 12.4 s                      |    Wall time: 3.99 s                       |
|                                           |                                            |
+-------------------------------------------+--------------------------------------------+

DASK on Mars
------------

更多信息请参阅 `DASK on Mars`_。

急切模式

Mars 支持急切模式，这使得开发更加友好且易于调试。

用户可以通过选项在程序或控制台会话的开始处启用急切模式。

.. code-block:: python

>>> from mars.config import options
>>> options.eager_mode = True

或者使用上下文管理器。

.. code-block:: python

>>> from mars.config import option_context
>>> with option_context() as options:
>>>     options.eager_mode = True
>>>     # 急切模式仅在 with 语句块内生效
>>>     ...

如果启用了急切模式，张量、DataFrame 等将在创建后默认由当前会话立即执行。

.. code-block:: python

>>> import mars.tensor as mt
>>> import mars.dataframe as md
>>> from mars.config import options
>>> options.eager_mode = True
>>> t = mt.arange(6).reshape((2, 3))
>>> t
array([[0, 1, 2],
       [3, 4, 5]])
>>> df = md.DataFrame(t)
>>> df.sum()
0    3
1    5
2    7
dtype: int64

Mars on Ray

Mars 也与 Ray 深度集成，可以高效地在 Ray <https://docs.ray.io/en/latest/>_ 上运行，并与基于 Ray 核心构建的庞大机器学习和分布式系统生态进行交互。

通过以下方式在本地启动一个新的 Mars on Ray 运行时：

.. code-block:: python

import mars
mars.new_session(backend='ray')
# 执行计算

与 Ray Dataset 交互：

.. code-block:: python

import mars.tensor as mt
import mars.dataframe as md
df = md.DataFrame(
    mt.random.rand(1000_0000, 4),
    columns=list('abcd'))
# 将 Mars DataFrame 转换为 Ray Dataset
ds = md.to_ray_dataset(df)
print(ds.schema(), ds.count())
ds.filter(lambda row: row["a"] > 0.5).show(5)
# 将 Ray Dataset 转换回 Mars DataFrame
df2 = md.read_ray_dataset(ds)
print(df2.head(5).execute())

更多信息请参阅 Mars on Ray_。

易于扩展和缩放

Mars 可以在单台机器上运行，也可以扩展到拥有数千台机器的集群中。从单机迁移到集群以处理更多数据或获得更好的性能，过程相当简单。

裸金属部署

通过在集群中的不同机器上启动 Mars 分布式运行时的不同组件，Mars 很容易扩展到集群环境中。

可以选择一台节点作为 Supervisor，该节点集成了 Web 服务，而其他节点则作为 Worker。Supervisor 可以使用以下命令启动：

.. code-block:: bash

    mars-supervisor -h <host_name> -p <supervisor_port> -w <web_port>

Worker 则可以使用以下命令启动：

.. code-block:: bash

    mars-worker -h <host_name> -p <worker_port> -s <supervisor_endpoint>

所有 Mars 进程启动完成后，用户可以执行：

.. code-block:: python

    >>> sess = new_session('http://<web_ip>:<ui_port>')
    >>> # 执行计算


Kubernetes 部署

更多信息请参阅 Run on Kubernetes_。

Yarn 部署

更多信息请参阅 `Run on Yarn`_。


参与贡献
----------------

- 阅读 `开发指南 <https://mars-project.readthedocs.io/en/latest/development/index.html>`_。
- 加入我们的 Slack 工作组：`Slack <https://join.slack.com/t/mars-computing/shared_invite/zt-17pw2cfua-NRb2H4vrg77pr9T4g3nQOQ>`_。
- 加入邮件列表：发送邮件至 `mars-dev@googlegroups.com`_。
- 请通过提交 `GitHub issue`_ 报告问题。
- 使用 `pull requests`_ 提交您的贡献。

感谢您提前做出的贡献！


.. |Build| image:: https://github.com/mars-project/mars/workflows/Mars%20CI%20Core/badge.svg
   :target: https://github.com/mars-project/mars/actions
.. |Coverage| image:: https://codecov.io/gh/mars-project/mars/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/mars-project/mars
.. |Quality| image:: https://img.shields.io/codacy/grade/6a80bb4659ed410eb33795f580c8615e.svg
   :target: https://app.codacy.com/project/mars-project/mars/dashboard
.. |PyPI version| image:: https://img.shields.io/pypi/v/pymars.svg
   :target: https://pypi.python.org/pypi/pymars
.. |Docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
   :target: `Documentation`_
.. |License| image:: https://img.shields.io/pypi/l/pymars.svg
   :target: https://github.com/mars-project/mars/blob/master/LICENSE
.. _`mars-dev@googlegroups.com`: https://groups.google.com/forum/#!forum/mars-dev
.. _`GitHub issue`: https://github.com/mars-project/mars/issues
.. _`pull requests`: https://github.com/mars-project/mars/pulls
.. _`Documentation`: https://mars-project.readthedocs.io
.. _`中文文档`: https://mars-project.readthedocs.io/zh_CN/latest/
.. _`Mars on Ray`: https://mars-project.readthedocs.io/en/latest/installation/ray.html
.. _`Run on Kubernetes`: https://mars-project.readthedocs.io/en/latest/installation/kubernetes.html
.. _`Run on Yarn`: https://mars-project.readthedocs.io/en/latest/installation/yarn.html
.. _`DASK on Mars`: https://mars-project.readthedocs.io/en/latest/user_guide/contrib/dask.html

Mars 快速上手指南

Mars 是一个基于张量的统一框架，旨在扩展 NumPy、Pandas 和 Scikit-learn 等库，使其能够进行大规模数据计算。它支持多核并行及分布式集群运行。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• Python 版本：建议 Python 3.8 及以上版本。
• 前置依赖：需安装 pip 包管理工具。
• 网络建议：国内用户若遇到下载缓慢，可配置清华或阿里镜像源加速安装。

安装步骤

1. 基础安装（推荐）

通过 PyPI 直接安装最新版本：

pip install pymars

国内加速安装：

pip install pymars -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 开发者安装

如果您需要贡献代码或修改源码，请克隆仓库并进行可编辑安装：

git clone https://github.com/mars-project/mars.git
cd mars
pip install -e ".[dev]"

基本使用

1. 启动会话

在使用 Mars 之前，需要先启动一个本地运行时会话或连接到现有集群。

启动本地会话：

>>> import mars
>>> mars.new_session()

连接远程集群：

>>> import mars
>>> mars.new_session('http://<web_ip>:<ui_port>')

2. 核心功能示例

Mars 提供了与主流科学计算库高度兼容的接口，只需少量改动即可实现并行加速。

Mars Tensor (替代 NumPy)

接口类似 NumPy，但需调用 .execute() 触发计算。

import mars.tensor as mt

N = 200_000_000
# 定义计算图（此时不执行）
a = mt.random.uniform(-1, 1, size=(N, 2))
result = ((mt.linalg.norm(a, axis=1) < 1).sum() * 4 / N)

# 触发执行并获取结果
print(result.execute())

Mars DataFrame (替代 Pandas)

接口类似 Pandas，适用于处理超大规模表格数据。

import mars.tensor as mt
import mars.dataframe as md

# 创建大规模 DataFrame
df = md.DataFrame(
    mt.random.rand(100000000, 4),
    columns=list('abcd')
)

# 执行聚合操作
print(df.sum().execute())

Mars Learn (替代 Scikit-learn)

提供熟悉的机器学习 API，支持大规模模型训练。

from mars.learn.datasets import make_blobs
from mars.learn.decomposition import PCA

# 生成大规模数据集
X, y = make_blobs(
    n_samples=100000000, n_features=3,
    centers=[[3, 3, 3], [0, 0, 0], [1, 1, 1], [2, 2, 2]],
    cluster_std=[0.2, 0.1, 0.2, 0.2],
    random_state=9
)

# 模型训练
pca = PCA(n_components=3)
pca.fit(X)

# 查看结果（自动触发执行）
print(pca.explained_variance_ratio_)

Mars Remote (并行执行函数)

允许将普通 Python 函数并行化执行。

import mars.remote as mr

def calc_chunk(n, i):
    import numpy as np
    rs = np.random.RandomState(i)
    a = rs.uniform(-1, 1, size=(n, 2))
    d = np.linalg.norm(a, axis=1)
    return (d < 1).sum()

N = 200_000_000
n = 10_000_000

# 并行 spawn 任务
fs = [mr.spawn(calc_chunk, args=(n, i)) for i in range(N // n)]
pi = mr.spawn(lambda fs, N: sum(fs) * 4 / N, args=(fs, N))

# 获取最终结果
print(pi.execute().fetch())

3. 调试模式：Eager Mode

默认情况下 Mars 采用懒执行（Lazy Execution）。在开发调试阶段，可开启“即时执行模式”（Eager Mode），使代码行为更像原生 NumPy/Pandas。

全局开启：

from mars.config import options
options.eager_mode = True

上下文临时开启：

from mars.config import option_context

with option_context() as options:
    options.eager_mode = True
    # 在此块内创建的 Tensor 或 DataFrame 会立即执行
    ...