メインコンテンツへスキップ

​
材料とは

材料 (Material) は、セル仕様で使用される物理材料を記述する再利用可能なレコードです。例えば、NMC811 正極粉末、グラファイト負極、LP57 電解液などです。材料は組織レベルに存在するため、同じ材料を複数のセルやプロジェクトから参照できます。 各材料には任意の数の プロパティデータセット を添付できます。プロパティデータセットは、1 つ以上の物理プロパティを 1 つ以上の独立変数の関数として表す表形式の測定（CSV または parquet）です。例えば、電解質導電率対濃度や、負極 OCP 対化学量論などです。プロパティデータセットはプロジェクトスコープなので、共有された同じ材料に対して各プロジェクトが独自の測定を保持できます。
プロパティデータセットはデータとして保存されます。ルックアップテーブルをパラメータ化モデルに直接埋め込むパラメータ補間子とは別物です。プロパティデータセットを使って生の測定を整理・共有し、シミュレーションで使用する準備ができたら補間子に変換してください。

​
材料の使いどころ

材料は次のような場合に使用します:
  • 複数のセル（例: 複数のセル構成における同じ電解液）にまたがって使用される材料のプロパティに関する単一の信頼できる情報源を維持したい。
  • 測定された材料と並べて、生の測定（OCP、拡散係数、導電率、輸率、…）を保存したい。
  • 同じプロパティの複数のデータセットを比較したい — 例えば、異なる温度や異なる研究室で測定された OCP カーブ。
  • 来歴を追跡したい: 誰が、いつ、どの生ファイルからデータセットをアップロードしたか。

​
UI で材料を管理する

各プロジェクトには左側のナビゲーションに Materials セクションがあります。そこで次のことが可能です:
  • 材料を作成する — 名前を付け、任意で製造元と製品 ID を指定します。
  • 材料を開く — プロパティデータセットとメタデータを表示します。
  • 行アクションメニューから材料を 編集または削除 します。
システム材料（すべての組織で共有）は読み取り専用で、関連する場合は組織の材料と並んで表示されます。

​
プロパティデータセットのアップロード

材料の詳細ページから Upload property dataset をクリックして:
  1. ファイルを選択する — CSV または parquet。CSV はヘッダー行を含むことも省略することもできます。
  2. データセットに名前を付ける — 例: Conductivity at 25 °C。
  3. 列を宣言する — 保持したい各列について次を提供します:
    • Name — 処理済みデータセットに格納される表示名（例: c_e）。
    • Unit — 物理単位（例: mol/L、S/m）。無次元量の場合は空白のままにします。
    • Source column — 値の取得元となるアップロードファイル内の列。ヘッダーなし CSV では位置です。ヘッダー付きのファイルでは名前で選択できます。
  4. 送信。 ファイルが解析され、すべての値が浮動小数点数に強制変換され（数値でないセルは NaN になります）、処理済み parquet と元の生ファイルの両方が保存されます。
アップロード後、データセットは材料のプロパティリストに、行数と列ごとの NaN カウントとともに表示され、解析の問題を素早く発見できます。

​
データセットのプロット

データセットをクリックすると plot ダイアログ が開きます。可能なこと:
  • データセットから x と y の列を選択します。
  • ズームとパン: プロットは大きなデータセットでも反応性を保つように、表示範囲の点を動的にダウンサンプリングして再取得します。
  • アクションメニューから処理済み parquet または元の生ファイルをダウンロードします。

​
データセットの編集

データセットの Edit アクションでは次が可能です:
  • データセットの名前を変更します。
  • 列名と単位を再宣言します。列が変更されると、保存された元のファイルから新しい仕様で parquet が再構築されます。再アップロードは不要です。
  • 同じデータセット ID とメタデータを保持したままデータファイルを完全に置き換えます。データセットを参照する他のレコードはリンクされたままです。
データを変更する編集ごとにデータセットの data_version がインクリメントされるため、下流のコンシューマーはキャッシュされた結果が古くなったことを検出できます。

​
REST API

材料プロパティデータセットは /material_property_datasets の下で管理されます。材料そのものは /materials の下で管理されます。

​
データセットのアップロード

POST /material_property_datasets は multipart フォームを受け入れます:
フィールド説明
fileアップロードする CSV または parquet ファイル。
material_id親材料の ID。
project_idこのデータセットがスコープされるプロジェクトの ID。
name人間可読のデータセット名。
columns列仕様の JSON 配列（下記参照）。
no_headerCSV にヘッダー行がない場合は true。デフォルトは false。
各列仕様はオブジェクトです: 
{
  "name": "c_e",
  "unit": "mol/L",
  "source_column_index": 0
}
source_column_index はアップロードファイル内の列の 0 始まりの位置です。ファイルにヘッダー行がある場合でも必須です。名前は位置で照合された後、提供した name にリネームされます。 curl でのアップロード例: 
curl -X POST "$IONWORKS_URL/material_property_datasets" \
  -H "Authorization: Bearer $IONWORKS_TOKEN" \
  -F "[email protected]" \
  -F "material_id=$MATERIAL_ID" \
  -F "project_id=$PROJECT_ID" \
  -F "name=Conductivity at 25 °C" \
  -F 'columns=[
    {"name": "c_e", "unit": "mol/L", "source_column_index": 0},
    {"name": "kappa", "unit": "S/m", "source_column_index": 1}
  ]'
レスポンスは新しいデータセットレコードで、id、storage_path、data_version、列ごとの nan_counts を含みます。

​
材料のデータセット一覧

curl "$IONWORKS_URL/material_property_datasets?material_id=$MATERIAL_ID&project_id=$PROJECT_ID&limit=100&offset=0" \
  -H "Authorization: Bearer $IONWORKS_TOKEN"
データセットレコードのページ分割されたリストを返します。

​
データセット値を JSON として取得する

curl "$IONWORKS_URL/material_property_datasets/$DATASET_ID/data?max_points=500&x_col=c_e&x_min=0&x_max=2" \
  -H "Authorization: Bearer $IONWORKS_TOKEN"
データセットを列指向の JSON オブジェクトとして返します: 
{
  "c_e": [0.5, 1.0, 1.5, 2.0],
  "kappa": [0.42, 0.71, 0.89, 0.95]
}
max_points は均一にダウンサンプリングするため、大きなデータセットでもプロットの反応性が保たれます。x_col、x_min、x_max はある列の範囲にレスポンスを制限します。チャートのズームに便利です。

​
元のファイルのダウンロード

GET /material_property_datasets/{id}/file を使ってファイル用の短命の署名付き URL にリダイレクトするか、GET /material_property_datasets/{id}/download-url で URL を JSON として受け取れます（ブラウザから開きたい場合に便利）。?kind=parquet（デフォルト）で処理済み parquet を、?kind=original でアップロードした生ファイルをダウンロードできます。

​
メタデータの更新、ファイルの置き換え、削除

エンドポイント説明
PATCH /material_property_datasets/{id}データセットの名前を変更したり列を再宣言したりします。列が変わると、保存された元のファイルから parquet が再構築されます。
PATCH /material_property_datasets/{id}/fileデータファイルを置き換えます。同じリクエストで任意に name、columns、no_header も更新できます。
DELETE /material_property_datasets/{id}データセットと保存されたファイルを削除します。

​
関連項目

  • セル — 材料はセル仕様の負極、正極、電解液、セパレーター構成要素から参照されます。
  • パラメータ補間子 — 測定されたプロパティデータをパラメータ化モデル内のルックアップテーブルパラメータに変換します。
  • データの概要 — Ionworks Studio で実験データがどのように整理されるか。