MathWorks.MATLAB.Engine.MATLABEngine

MATLAB を計算エンジンとして使用する .NET クラス

R2022b 以降

説明

MATLABEngine クラスは .NET アプリケーションの計算エンジンとして MATLAB® プロセスを使用します。MATLAB 関数は呼び出しによって動的に起動するため、MATLABEngine オブジェクトのメソッドとして呼び出すことができます。また、定義した関数およびスクリプトを呼び出すこともできます。MATLABEngine オブジェクトに関連付けられている MATLAB ワークスペースにデータを送信したり、そこからデータを取得したりできます。

MATLABEngine クラスを使用して新しい MATLAB セッションを開始するか既存のセッションに接続します。

例外の詳細については、MathWorks.MATLAB.Exceptions Exception Classes for .NETを参照してください。

クラスの詳細

名前空間:

MathWorks.MATLAB.Engine
スーパークラス:System.Dynamic.DynamicObject
インターフェイス:System.IDisposable

サポートされない起動オプション

エンジンは次の MATLAB 起動オプションをサポートしていません。

  • -h

  • -help

  • -?

  • -n

  • -e

  • -logfile

MATLAB の起動オプションの詳細については、よく使われる起動オプションを参照してください。

メソッドの概要

静的メソッド

StartMATLAB

MATLAB を同期的に起動します。

StartMATLABAsync

MATLAB を非同期的に起動します。

ConnectMATLAB

共有 MATLAB セッションに同期的に接続します。

ConnectMATLABAsync

共有 MATLAB セッションに非同期的に接続します。

FindMATLAB

共有 MATLAB セッションを同期的に検索します。

FindMATLABAsync

共有 MATLAB セッションを非同期的に検索します。

Dispose

using ステートメントによって作成されたリソースを解放するために暗黙的に呼び出されます。

TerminateEngineClient

すべての MATLAB リソースを実行時に解放します。

メンバー変数

WorkspaceMATLAB ベース ワークスペースへのアクセス。グローバル ワークスペースへのアクセスはサポートされていません。

特殊な演算子と関数

dynamic 型の変数に代入する際に MATLABEngine オブジェクトのメソッドとして、任意の MATLAB 関数を呼び出すことができます。MATLAB 関数呼び出しによって、エンジンは関数を動的に呼び出します。詳細については、MATLAB 関数の呼び出しを参照してください。

メソッドの詳細

StartMATLAB

static MATLABEngine StartMATLAB();

static MATLABEngine StartMATLAB(string option);

static MATLABEngine StartMATLAB(string option1, ..., string optionN);

static MATLABEngine StartMATLAB(string[] options);

説明

オプションの MATLAB 起動オプションを使用して、MATLAB を別プロセスで同期的に起動して接続します。

パラメーター

string option
string[] options

MATLAB エンジンを起動するために使用する起動オプション。複数の起動オプションを指定できます。エンジンはサポートされない起動オプションに記載されているオプションを除くすべての MATLAB 起動オプションをサポートしています。オプションのリストについては、プラットフォーム固有の matlab (Windows) コマンド、matlab (macOS) コマンド、または matlab (Linux) コマンドを参照してください。

戻り値

共有 MATLAB セッションに接続された MATLABEngine のインスタンス

スロー

MathWorks.MATLAB.Exceptions.MATLABNotAvailableException

MATLAB が起動しません。

System.ArgumentNullExceptionヌル string は有効な引数ではありません。
C# の例

1 つの起動オプションを指定して新しい MATLAB プロセスを開始します。完全なコードの例については、-nodesktop オプションを指定した MATLAB の起動を参照してください。

using (dynamic eng = MATLABEngine.StartMATLAB("-nodesktop"))
{
    eng.disp(new RunOptions(nargout: 0), "MATLAB started.");
}
VB.NET の例

既定のオプションを指定して新しい MATLAB プロセスを開始します。

Option Strict Off
Using matlab As Object = MATLABEngine.StartMATLAB()
  matlab.disp(New RunOptions(nargout:=0), "Hello, world.")
End Using

StartMATLABAsync

static Task<MATLABEngine> StartMATLABAsync();

static Task<MATLABEngine> StartMATLABAsync(string option);

static Task<MATLABEngine> StartMATLABAsync(string option1, ..., string optionN);

static Task<MATLABEngine> StartMATLABAsync(string[] options, System.Threading.CancellationToken token);

説明

オプションの MATLAB 起動オプションを使用して、MATLAB を別プロセスで非同期的に起動して接続します。

パラメーター

string option
string[] options

MATLAB エンジンを起動するために使用する起動オプション。複数の起動オプションを指定できます。エンジンはサポートされない起動オプションに記載されているオプションを除くすべての MATLAB 起動オプションをサポートしています。オプションのリストについては、プラットフォーム固有の matlab (Windows) コマンド、matlab (macOS) コマンド、または matlab (Linux) コマンドを参照してください。

CancellationToken token

非同期タスクのキャンセルに使用されるキャンセル トークン。既定値は System.Threading.CancellationToken.None です。

戻り値

MATLABEngine オブジェクトがインスタンス化されて MATLAB に接続されるか、キャンセル要求を受信するか、例外が発生したときに完了したタスク

スロー

MathWorks.MATLAB.Exceptions.MATLABNotAvailableException

MATLAB が起動しません。

System.OperationCanceledExceptionSystem.Threading.CancellationToken から受信したキャンセル要求。
System.ArgumentNullExceptionヌル string は有効な引数ではありません。
C# の例

バックグラウンドで 2 つの MATLAB セッションを開始し、両方とも開始するまで待ってから続行します。完全なコードの例については、2 つの MATLAB セッションの非同期的開始を参照してください。

try
{
    Task<MATLABEngine> startMatlab1 = MATLABEngine.StartMATLABAsync();
    Task<MATLABEngine> startMatlab2 = MATLABEngine.StartMATLABAsync();
            
    Console.WriteLine("Two MATLAB sessions are starting in the background.");
    Console.WriteLine("Wait for both to start before continuing.");
    await Task.WhenAll(startMatlab1, startMatlab2);
    Console.WriteLine("Two MATLAB sessions started.");
} 
catch (MATLABNotAvailableException) 
{
    Console.WriteLine("Could not start or connect to MATLAB engine.");
}

MATLAB を非同期的に開始しますが、演算にかかっている時間が 10 秒を超えたらキャンセルします。

// Create a cancel token source, and set it to cancel after 10 seconds
CancellationTokenSource src = new CancellationTokenSource();
src.CancelAfter(TimeSpan.FromSeconds(10));
try {
    // Wait for the task to complete
    dynamic matlab = await MATLABEngine.StartMATLABAsync(src.Token);
    Console.WriteLine("MATLAB has started.");

} catch (MATLABNotAvailableException) {
    // Could not connect to MATLAB
    Console.Error.WriteLine("Could not start or connect to MATLAB engine.");
} catch (OperationCanceledException) {
    // Task was canceled before MATLAB started
    Console.Error.WriteLine("Task was canceled before completion.");
} finally {
    src.Dispose();
}

ConnectMATLAB

static MATLABEngine ConnectMATLAB();

static MATLABEngine ConnectMATLAB(string name);

説明

ローカル マシン上の共有 MATLAB セッションに同期的に接続するか、セッションが存在しない場合は新しいセッションを開始します。

  • 共有 MATLAB セッションの名前を指定してもエンジンがその名前のセッションを見つけられない場合、エンジンは MathWorks.MATLAB.Exceptions.MATLABNotAvailableException をスローします。

  • 名前を指定せず、使用可能な共有 MATLAB セッションがない場合、エンジンは既定のオプションを使用して新しい共有 MATLAB セッションを開始します。

  • 名前を指定せず、使用可能な共有 MATLAB セッションが存在する場合、エンジンは使用可能な最初のセッションに接続します。

パラメーター

string name

共有 MATLAB セッションの名前。FindMATLAB を使用して、共有 MATLAB セッションの名前を取得します。

戻り値

MATLABEngine のインスタンス

スロー

MathWorks.MATLAB.Exceptions.MATLABNotAvailableException

MATLAB の起動または接続が失敗しました。

System.ArgumentNullExceptionヌル string は有効な引数ではありません。.
C# の例

見つかった最初の共有 MATLAB セッションに接続するか、新しいセッションを開始します。

using (dynamic matlab = MATLABEngine.ConnectMATLAB()) {
    matlab.disp(new RunOptions(nargout: 0), "Hello, shared MATLAB."); }

共有 MATLAB セッションに名前で接続します。

using (dynamic matlab = MATLABEngine.ConnectMATLAB("MATLAB_1234")) {
    matlab.disp(new RunOptions(nargout: 0), "Hello, MATLAB_1234.");

MATLAB_1234 を検出できないか接続できない場合にメッセージが表示される例については、MathWorks.MATLAB.Exceptions.MATLABNotAvailableExceptionを参照してください。

VB.NET の例

見つかった最初の共有 MATLAB セッションに接続するか、新しいセッションを開始します。

Using matlab As Object = MATLABEngine.ConnectMATLAB()
  matlab.disp(New RunOptions(nargout: 0), "Hello, shared MATLAB.")
End Using

共有 MATLAB セッションに名前で接続します。

Option Strict Off
Using matlab As Object = MATLABEngine.ConnectMATLAB("MATLAB_1234")
    matlab.disp(New RunOptions(nargout:=0), "Hello, "MATLAB_1234.")
End Using

MATLAB_1234 を検出できないか接続できない場合にメッセージが表示される例については、MathWorks.MATLAB.Exceptions.MATLABNotAvailableExceptionを参照してください。

ConnectMATLABAsync

static Task<MATLABEngine> ConnectMATLABAsync();

static Task<MATLABEngine> ConnectMATLABAsync(string name);

static Task<MATLABEngine> ConnectMATLABAsync(System.Threading.CancellationToken token);

static Task<MATLABEngine> ConnectMATLABAsync(string name, System.Threading.CancellationToken token);

説明

ローカル マシン上の共有 MATLAB セッションに非同期的に接続するか、セッションが存在しない場合は新しいセッションを開始します。

  • 共有 MATLAB セッションの名前を指定してもエンジンがその名前のセッションを見つけられない場合、エンジンは MathWorks.MATLAB.Exceptions.MATLABNotAvailableException をスローします。

  • 名前を指定せず、使用可能な共有 MATLAB セッションがない場合、エンジンは既定のオプションを使用して新しい共有 MATLAB セッションを開始します。

  • 名前を指定せず、使用可能な共有 MATLAB セッションが存在する場合、エンジンは使用可能な最初のセッションに接続します。

パラメーター

string name

共有 MATLAB セッションの名前。FindMATLABAsync を使用して、共有 MATLAB セッションの名前を取得します。

CancellationToken token

非同期タスクのキャンセルに使用されるキャンセル トークン。既定値は System.Threading.CancellationToken.None です。

戻り値

MATLABEngine オブジェクトがインスタンス化されて MATLAB に接続されるか、キャンセル要求を受信するか、例外が発生したときに完了したタスク

スロー

MathWorks.MATLAB.Exceptions.MATLABNotAvailableException

MATLAB の起動または接続が失敗しました。

System.OperationCanceledExceptionSystem.Threading.CancellationToken から受信したキャンセル要求。
System.ArgumentNullExceptionヌル string は有効な引数ではありません。

FindMATLAB

static string[] FindMATLAB();

説明

ローカル マシン上のすべての共有 MATLAB セッションを同期的に検索します。

パラメーター

なし

戻り値

ローカル マシン上の共有 MATLAB セッションすべての名前からなる配列、または使用可能なセッションがない場合は空の配列

C# の例

特定の MATLAB セッションに接続します。

// Find shared MATLAB sessions
string[] names = MATLABEngine.FindMATLAB(); 
if (names.Length == 0)
    Console.Error.WriteLine("No shared MATLAB sessions found.");
string myMATLAB = names[0]; // Pick the first
using (dynamic matlab = MATLABEngine.ConnectMATLAB(myMATLAB)) {
    matlab.disp(new RunOptions(nargout: 0), "Hello, shared MATLAB.");
VB.NET の例

特定の MATLAB セッションに接続します。

Option Strict Off
'Find shared MATLAB sessions
Dim names As String() = MATLABEngine.FindMATLAB() 
If names.Length = 0 Then
    Console.Error.WriteLine("No shared MATLAB sessions found.")
End If
Dim myMATLAB = names(0) 'Pick the first
Using matlab As Object = MATLABEngine.ConnectMATLAB(myMATLAB)
    matlab.disp(New RunOptions(nargout:=0), "Hello, shared MATLAB.")
End Using

FindMATLABAsync

static Task<string[]> FindMATLABAsync();

static Task<string[]> FindMATLABAsync(System.Threading.CancellationToken token);

説明

ローカル マシン上のすべての共有 MATLAB セッションの名前を非同期的に検索して返します。

パラメーター
CancellationToken token

非同期タスクのキャンセルに使用されるキャンセル トークン。既定値は System.Threading.CancellationToken.None です。

戻り値

完了したタスクと、ローカル マシン上のすべての共有 MATLAB セッションの名前の配列

スロー
System.OperationCanceledExceptionSystem.Threading.CancellationToken から受信したキャンセル要求。
C# の例

見つかった最初の共有 MATLAB セッションに接続します。

static async void Main(string[] args) {
    string[] names = await MATLABEngine.FindMATLABAsync();
    if (names.Length == 0)
        Console.WriteLine("No MATLAB sessions available.");
    else
    {
        dynamic matlab = await MATLABEngine.ConnectMATLABAsync(names[0]);
        matlab.disp(new RunOptions(nargout: 0), "Hello, shared MATLAB.");
    }
}

Dispose

static void Dispose();

説明

using ステートメントによって作成されたリソースを解放するために暗黙的に呼び出されます。

C# の例
// Wrap in a using block to ensure proper disposal of unmanaged resources.
using (dynamic eng = MATLABEngine.StartMATLAB()) {
    eng.disp(new RunOptions(nargout: 0), "Hello, world.");
} // MATLABEngine.Dispose() is implicitly called when "eng" goes out of scope.
VB.NET の例
Option Strict Off
'Wrap in a using block to ensure proper disposal of unmanaged resources.
Using eng As Object = MATLABEngine.StartMATLAB()
    eng.disp(New RunOptions(nargout:=0), "Hello, world.")
End Using
'MATLABEngine.Dispose() is implicitly called when "eng" goes out of scope.

TerminateEngineClient

static void TerminateEngineClient();

説明

すべての MATLAB リソースを実行時に解放します。

C# の例
using (dynamic matlab = MATLABEngine.StartMATLAB()) {
    matlab.disp(new RunOptions(nargout: 0), "Hello, world.");
}
MATLABEngine.TerminateEngineClient();
VB.NET の例
Option Strict Off
Using matlab As Object = MATLABEngine.StartMATLAB()
    matlab.disp(New RunOptions(nargout:=0), "Hello, world.")
End Using
MATLABEngine.TerminateEngineClient();

MATLAB 関数の呼び出し

ret = MATLABEngine.matlabfunc(dynamic arg1, ..., dynamic argN);

ret = MATLABEngine.matlabfunc(RunOptions options, __);

ret = MATLABEngine.matlabfunc(__, Name: Value);

ret = MATLABEngine.matlabfunc(__, "Name", Value);

説明

MATLAB 関数 matlabfunc を呼び出します。

パラメーター

dynamic arg1, ..., dynamic argN

既定の実行オプションを使用した MATLAB 関数の引数。dynamic 型を使用して、必須パラメーター、位置パラメーター、名前付きパラメーター、およびオプション パラメーターの型を実行時に解決します。MATLAB 関数によって arg1, ..., argN の型が判別されます。

RunOptions options

関数の実行オプション。MathWorks.MATLAB.Types.RunOptions オブジェクトとして指定します。関数の引数の前に実行オプションを指定します。

Name および Value

引数のペア。次のいずれかの形式で指定します。

  • Name: Value

  • "Name", Value

ここで、Name は引数名で、Value は対応する値です。前述の任意の構文で、すべての引数の後に名前と値の引数を指定します。

戻り値

MATLAB 関数の出力。同期的に呼び出された関数の場合、返される値は次のとおりです。

  • MATLAB コマンドの場合は、null

  • 出力が単一の関数の場合は、関数の出力

  • 出力が複数ある関数の場合は、各出力をラップする ValueTuple

非同期的に呼び出された関数の場合、返される値は、MATLAB 関数の完了時、例外の発生時、またはタスクのキャンセル時に完了した Task です。Task.Result プロパティには、関数の出力が含まれます。

スロー

MathWorks.MATLAB.Exceptions.MATLABNotAvailableException

MATLAB への接続が失われました。

MathWorks.MATLAB.Exceptions.MATLABExecutionException

MATLAB 実行時エラーが発生しました。

MathWorks.MATLAB.Exceptions.UnsupportedTypeException

MATLAB 関数へのパラメーターをネイティブの MATLAB 型に変換できません。

System.InvalidCastException

MATLAB 関数からの戻り値を所定の .NET 型にキャストできません。

System.OperationCanceledException

System.Threading.CancellationToken から受信したキャンセル要求。

C# の例

エンジン オブジェクト matlab で MATLAB 関数 linspace を呼び出します。完全なコードの例については、.NET から MATLAB への変数の引き渡しを参照してください。

double[] A = matlab.linspace(-5.0,5.0);

バージョン履歴

R2022b で導入

参考