Helionyx

Helionyx

AI アシスタントとの対話でハイブリッドエネルギーシステムの規模を設計できます。 Helionyx は、太陽光発電、風力、蓄電池、ディーゼル発電機、および系統連系システムの規模を設計するオープンソースの Model Context Protocol（MCP）サーバーです。従来の技術経済性評価ワークフローを実行します。

1. すべての設計候補について、1年分を1時間ごとにシミュレーションします。
2. 制約に違反する設計を除外します。
3. 残りを正味現在費用（NPC）で順位付けし、投資回収期間、LCOE、電気料金、排出量も提示します。

アシスタントが数値を捏造することはありません。条件を確認する質問をし、決定論的なツールを呼び出して結果を説明します。すべての数値は実行ID付きのソルバー実行から得られるため、誰でも再現できます。予備実現可能性調査、顧客向け提案書、地方電化計画、教育、他のツールとの照合に利用できます。

Helionyx を選ぶ理由

• 根拠に基づく回答： すべての数値はソルバーが算出し、アシスタントはその説明のみを行います。
• 包括的な手法： 1時間ごとの電力需給制御（負荷追従、サイクル充電、TOU 系統戦略）、ライフサイクル経済性、TOU・デマンド料金・余剰電力の売電制度に対応した料金体系、系統停電に対応します。
• 単一の答えにとどまらない分析： 感度分析グリッド、コスト・CO₂・信頼性間のパレートトレードオフ、段階的な拡張を伴う複数年の負荷増加に対応します。
• 相互検証済み： 同じシナリオを使って、REopt、MicroGridsPy、SAMA と比較できます。
• オープンでローカル： Apache-2.0 ライセンスで、お使いのマシン上で動作します。付属データを使ってオフラインで利用でき、HOMER 対応の時系列データと Excel レポートをエクスポートできます。

はじめに

AI ツールの利用方法に合わせて選んでください。どの方法も約1分で完了します。

クライアント	インストール
Claude Code	claude mcp add helionyx -- uvx helionyx serve
Claude Desktop	最新リリースから helionyx-…-claude-desktop.mcpb をダウンロードして開きます
Smithery	smithery.ai/servers/gitdevjay/helionyx
任意のMCPクライアント（stdio）	コマンド uvx、引数 helionyx serve（uv が必要）
Python	pip install helionyx を実行し、続けて helionyx serve を実行します

次のように尋ねてみてください。

ネゴンボにある60室のホテル向けに、CEBのホテル料金体系を適用した太陽光発電・蓄電池システムの規模を設計してください。利用可能な屋根面積は約1,200 m²です。

クイックスタートでは、10分以内に最初の調査を行う手順を説明しています。

Helionyx の入手先

場所	リンク
ソースコードとリリース	github.com/Jayzilva/helionyx · リリース
PyPI	pypi.org/project/helionyx
Smithery	smithery.ai/servers/gitdevjay/helionyx
公式 MCP Registry	io.github.Jayzilva/helionyx (レジストリエントリー、JSON)

データと精度

Helionyx には、スリランカ向けの国別パック（lk）が付属しています。CEB と LECO の料金体系および売電制度、Asia/Colombo 時刻に合わせた気象データ、送電網の停電パターン、スリランカの建物の負荷アーキタイプが含まれています。エンジン自体は国に依存しません。新しい国はデータパックとして追加できます（データパックガイド）。

lk パックの料金、コンポーネント費用、燃料価格、割引率、排出係数は未検証の仮置き値です。 データが検証されるまでは、ツールの使い方を学び、選択肢を比較するために結果を利用し、実際の意思決定には使用しないでください。validate_scenario は未検証の料金ごとに警告 HNX-W001 を発生させます。免責事項をご覧ください。

リリースと変更点は変更履歴に記載されています。Microsoft Entra ID サインインと OpenTelemetry モニタリングを備えたホストモードは、1.0 に向けて開発中です。

アーキテクチャ

flowchart LR
    U([User]) <--> C["MCP client<br/>Claude Code · Claude Desktop<br/>Copilot Studio · custom agent"]
    C <-->|"stdio or<br/>Streamable HTTP"| S

    subgraph H["Helionyx (local-first, deterministic)"]
        S["MCP server<br/>22 tools · 9 resources · 6 prompts"]
        S --> SV["Services<br/>scenario · run · sensitivity · results · export"]
        SV --> K["Engine<br/>Numba dispatch kernel · pvlib · economics · billing"]
        SV --> ST[("SQLite metadata<br/>Parquet artefacts")]
        SV --> P["Country packs<br/>tariffs · components · archetypes"]
    end

    SV -.->|"HTTPS, cached"| W["NASA POWER · PVGIS"]
    SV -.->|"cross-check"| R["REopt v3 API"]
    SV -.->|"JSON subprocess"| X["helionyx-microgridspy (EUPL)<br/>helionyx-sama (AGPL)"]

サーバーが LLM を呼び出すことはありません。コピーレフトライセンスのソルバーは別プロセスとして実行されるため、コアは Apache-2.0 のままです。

サイジングの会話例

sequenceDiagram
    autonumber
    actor User
    participant AI as AI assistant
    participant HX as Helionyx tools
    User->>AI: "Size PV and a battery for my 60-room hotel in Negombo"
    AI->>HX: create_site, fetch_resource, synthesize_load
    AI->>HX: list_tariffs, compute_bill (baseline)
    AI->>HX: create_scenario, validate_scenario
    HX-->>AI: assumptions and warnings
    AI->>User: confirm assumptions?
    User->>AI: yes
    AI->>HX: run_optimization → get_job_status
    AI->>HX: get_results, explain_run, get_monthly_summary
    HX-->>AI: ranked designs, NPC, bills, run ID
    AI->>User: top three designs, every number cited to the run

ソルバー

ソルバー	手法	用途	ライセンスとインストール
native	全列挙、8,760 時間のディスパッチ	デフォルト。探索空間における厳密な最適解	組み込み
heuristic	シード付きマルチスタートパターンサーチ	全列挙の上限を超える探索空間。最大 5,000 万候補を、50～50,000 回の評価予算内でサンプリングします（デフォルトは 4,000 回）	組み込み
reopt	完全先読みを用いた MILP（NREL REopt v3）	系統連系設計の相互検証	API キーが必要。負荷データはマシンの外部に送信されます
microgridspy	HiGHS を使用する LP	オフグリッド設計の相互検証	helionyx-microgridspy、EUPL-1.2
sama	粒子群最適化	オフグリッド設計の相互検証	helionyx-sama、AGPL-3.0

compare_runs を使うと、結果を並べて比較できます。複数年シナリオは native と heuristic でのみ実行できます。

複数年分析

シナリオに multi_year を追加すると、負荷を増加させながら段階的な投資を探索できます。

multi_year:
  load_growth_rate: 0.03        # year y load = year-1 load × 1.03^(y−1)
  sample_every_years: 5         # plus each stage boundary and the last year
  expansion:
    - year: 10
      pv_add_kwp: [0, 50, 100]
      bess_add_kwh: [0, 150]

拡張規模は追加の探索軸になります。段階ごとの資本支出は、その年のキャッシュフローに計上され、独自の交換費用と残存価値が適用されます。また、信頼性の制約はすべてのサンプル年で満たす必要があります。各候補は、サンプル年を multi_year.years に報告します。 方法論（判断 D20）をご覧ください。

特長

• リソースデータ： NASA POWER（対象地域ではPVGISも）の時間別GHI、気温、風速、CSVのインポート、ディスク上のキャッシュ、オフラインモード、UTCから現地標準時への調整、うるう日の削除と欠損値の補完。スリランカの3地点についてNASA POWERの2023年データが同梱されているため、リファレンスケースをオフラインで実行できます。
• 負荷プロファイル： 11種類の合成アーキタイプ、シード指定によるランダムな変動、12か月分の請求額に基づく調整、複合負荷、実測負荷のインポート（15／30／60分）。
• 料金体系と請求額： 定額、段階別、時間帯別の電力量料金、固定料金、デマンド料金、最低料金、賦課金に対応したバージョン管理付きYAML料金体系、およびネットメータリング、ネットアカウンティング、ネットプラス輸出方式。
• シナリオビルダー： 国別パックのデフォルト値、すべての値の出所、ソース、日付を記録する完全な仮定監査、検証ルール、SHA-256シナリオハッシュ、バージョン管理、YAMLの往復変換。計画停電とランダムな停電。
• シミュレーションと最適化： Numbaによる8,760時間のディスパッチカーネル（pvlibによるPV、風力発電曲線、理想化バッテリー、負荷追従またはサイクル充電に対応したディーゼル発電機、系統連系の時間帯別料金戦略）、並列全数探索、HOMER形式の経済性分析（NPC、LCOE、交換、残存価値、投資回収期間、IRR）、排出量。
• 探索： 全数探索、または候補数が5,000万までの探索空間に対応したシード付きヒューリスティックパターン探索。NPC、CO₂、容量不足のパレートフロント。
• 複数年分析： 年間負荷増加と最大3段階の容量拡張に対応し、初期システムと合わせて探索し、年ごとにコストを算出します。
• 感度分析： 再最適化を伴う単一変数のスイープと2変数グリッド、各ケースの最適なシステム構成、NPC弾性値。
• 根拠に基づく説明： コストの構成、コスト要因、制約条件、ディスパッチ統計、比較を構造化して提示します。すべての結果に、出典情報と免責事項が含まれます。
• エクスポート： HOMERにインポート可能な系列とパラメータシート、MarkdownおよびExcelレポート、時間別時系列、シナリオYAML。
• 相互検証ソルバー： compare_runsで比較できます。REopt v3（APIキーが必要）、MicroGridsPy、SAMAは個別ライセンスのアドオンパッケージとして提供されます（docs/adapters.mdを参照）。
• HOMERパリティキット： プロトコル、結果テンプレート、helionyx parity compare。
• ガイド付きワークフロー用のClaudeスキルとMCPプロンプト、および根拠確認ツール。

ソースからインストール

開発環境向け（Python 3.11～3.13）：

git clone https://github.com/Jayzilva/helionyx.git
cd helionyx
uv venv
uv pip install -e ".[dev]"      # or: python -m venv .venv, then pip install -e ".[dev]"

プルリクエストの前に実行するチェックについては、CONTRIBUTINGを参照してください。

コマンドラインのクイックスタート

コマンドラインからリファレンスケースを実行します（オフラインで動作します）。

helionyx run reference_cases/rc2_hotel_negombo.yaml

これは、CEBのホテル向け時間帯別料金で、ネゴンボにある60室のホテルのPVとバッテリー容量を算定し、系統のみのベースケースとともに、NPCが最も低い5つの設計を出力します。初回実行時は、Numbaがディスパッチカーネルをコンパイルするため、少し時間がかかります。

詳しい手順については、docs/quickstart.mdを参照してください。

AIアシスタントに接続する

Claude Code

claude mcp add helionyx -- uvx helionyx serve

Claude Desktop

最新リリースから.mcpbバンドルをダウンロードして開くと、Claude DesktopがHelionyxをインストールし、任意の設定（ワークスペースフォルダー、オフラインモード、REopt APIキー）を尋ねます。または、claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "helionyx": {
      "command": "uvx",
      "args": ["helionyx", "serve"]
    }
  }
}

ストリーミング可能なHTTP（ローカルテスト専用）

helionyx serve --transport http --port 8080

MCPをhttp://127.0.0.1:8080/mcpで、ヘルスチェックを/healthzで提供します。HNX_API_KEYを設定すると、Authorization: Bearer <key>が必須になります（開発用途の保護機能です。CLIはこれを設定せずに非ローカルバインドすることを拒否します）。Microsoft Entra IDを使用したOAuth 2.1は、v1.0のホストモードで利用可能になります。

Claude スキル

Claude が Helionyx のワークフローと根拠に基づく回答のルールに従うよう、スキルをコピーしてください。

cp -r skills/helionyx ~/.claude/skills/

スキルに対応していないクライアントでは、代わりに以下の MCP プロンプトを使用できます。docs/skill-guide.md を参照してください。

MCP ツール

#	ツール	用途
1	create_site	サイト（所在地、タイムゾーン、国別パック）を登録します
2	fetch_resource	NASA POWER または PVGIS から、現地時間に合わせた時間ごとの GHI、気温、風速を取得します
3	import_timeseries	CSV から実測の負荷またはリソース系列をインポートします。4 週間以上の負荷データを 1 年分に延長します
4	synthesize_load	アーキタイプから負荷を作成し、必要に応じて月々の請求額に合わせて調整します
5	list_tariffs	料金プランパックを確認します
6	get_tariff	料金、TOU 期間、余剰電力の買取制度、鮮度に関する警告を取得します
7	compute_bill	負荷に対する基準請求額、または買電・売電系列に対する請求額を計算します
8	list_components	コンポーネントライブラリを確認します
9	create_scenario	すべての入力と探索空間を組み合わせてシナリオを作成します
10	validate_scenario	エラー、警告、前提条件の完全な監査を表示します
11	run_optimization	非同期ジョブを開始します：native（列挙）、heuristic、reopt、microgridspy、または sama
12	get_job_status	ジョブの状態、進捗、完了予定時間、実行 ID を確認します
13	cancel_job	ジョブをキャンセルします
14	get_results	ランク付けされた設計、ベースケース、探索方法、出所、免責事項を取得します
14b	get_pareto_front	NPC、CO₂、容量不足に関する非劣解を取得します
15	explain_run	1 つの設計について、構造化された説明を取得します
16	get_monthly_summary	実施前後の月ごとのエネルギーフローと請求額を取得します
17	run_sensitivity	1 変数のスイープ、または再最適化を伴う 2 変数のグリッドを実行します（非同期）
18	get_sensitivity_results	値ごとの最適設計と NPC の弾力性を取得します
19	compare_runs	実行結果を並べて比較します（例：native と REopt）
20	export_homer_csv	HOMER にインポート可能な系列とパラメーターシートをエクスポートします
21	export_report	クライアント向けレポートを Markdown または Excel 形式で作成します

run_optimization、run_sensitivity、get_job_status は wait_seconds（0～20）を受け付けます。 0 を指定するとすぐに返され、それ以外の場合は待機して進捗通知を送信します。

リソース

URI	内容
hnx://packs/{country}/tariffs/{tariff_id}	料金プランの定義（JSON）
hnx://packs/{country}/components/{type}	コンポーネントライブラリの項目（JSON）
hnx://packs/{country}/archetypes/{archetype}	負荷アーキタイプの定義（JSON）
hnx://datasets/{dataset_id}.csv	時間ごとのリソースまたは負荷系列
hnx://scenarios/{scenario_id}	正規化されたシナリオ（JSON）
hnx://runs/{run_id}/results.csv	サイズ、指標、実現可能性を含むすべての候補
hnx://runs/{run_id}/candidates/{rank}/timeseries.csv	候補の時間ごとのフロー
hnx://runs/{run_id}/report.md	生成されたレポート
hnx://docs/methodology	方程式と、HOMER との相違点の記録

プロンプト

プロンプト	用途
size_cni_rooftop_tou	TOU 料金プランを適用する商業用または産業用の屋上 PV ＋バッテリー
size_offgrid_village	オフグリッドの村落マイクログリッド
diesel_replacement_island	既存のディーゼルシステムをハイブリッド化します
explain_for_client	技術者または経営層向けの、根拠に基づく説明
homer_crosscheck	HOMER Pro へのガイド付きエクスポートと比較チェックリスト
teach_me	小規模な実行例を使ったチュートリアル

コマンドラインインターフェース

コマンド	目的
helionyx serve [--transport stdio|http] [--host] [--port]	MCP サーバーを起動します
helionyx run <study.yaml> [--solver native] [--top 5] [--sort-by npc]	スタディまたはシナリオファイルを実行します
helionyx results <run_id> [--top 10]	結果を出力します
helionyx export homer <scenario_id> <dir>	HOMER ファイルを書き出します
helionyx export report <run_id> [--format md] [--output path]	レポートを書き出します
helionyx pack validate <path>	データパックを検証します
helionyx pack build <path> <out_dir>	リリースアーカイブとチェックサムマニフェストを作成します（メンテナー向け）
helionyx pack update [--country lk] [--manifest URL]	チェックサムを検証済みの新しいデータパックリリースをインストールします
helionyx parity compare <homer.csv> [--output report.md]	RC-1〜RC-3について、HOMER Pro の結果と Helionyx の結果を比較します
helionyx eval grounding <transcripts_dir> [--threshold 0.95]	グラウンディングチェッカーを実行します
helionyx version	バージョンを出力します

設定

.env.exampleをコピーするか、次の環境変数を設定してください。

変数	デフォルト値	意味
HNX_WORKSPACE	~/.helionyx	データベース、アーティファクト、キャッシュ、エクスポート用のワークスペースです。この範囲外のファイルパスは拒否されます。
HNX_OFFLINE	0	1にすると、キャッシュ済みデータと同梱データのみを使用します。ネットワーク呼び出しは行いません
HNX_MAX_JOBS	2	ユーザーごとの同時実行ジョブの最大数
HNX_JOB_TIMEOUT_S	900	ジョブの制限時間（秒）
HNX_REOPT_API_KEY	—	REopt API キー（developer.nlr.gov）
HNX_REOPT_FIXTURE	—	API を呼び出す代わりに、記録済みの REopt レスポンスを再生します（テスト用）
HNX_REOPT_URL	https://developer.nlr.gov/api/reopt/stable	REopt のベース URL
HNX_LOG_LEVEL	INFO	ログレベル
HNX_API_KEY	—	HTTP モードで必要なベアラーキー（開発用）。ローカル以外のアドレスにバインドする場合に必要です
HNX_MICROGRIDSPY_CMD	helionyx-microgridspy	MicroGridsPy アダプターパッケージのコマンド
HNX_SAMA_CMD	helionyx-sama	SAMA アダプターパッケージのコマンド

リポジトリの構成

src/helionyx/
  api/            MCP server, CLI, Streamable HTTP host, output schemas
  services/       site/resource, load, tariff, scenario, run, sensitivity, results, export, study
  core/           Pydantic models, engine (PV, wind, dispatch kernel, outages), economics, billing
  adapters/       solver adapter interface and REopt v3 adapter
  infra/          settings, SQLite store, Parquet artefact store, HTTP cache, jobs, pack loader
  packs/lk/       Sri Lanka country pack (tariffs, components, archetypes, emissions, defaults, samples)
  templates/      report and HOMER parameter templates, methodology
packages/         separately licensed solver adapters (helionyx-microgridspy, helionyx-sama)
skills/helionyx/  Claude skill
reference_cases/  RC-1 to RC-3 study files
evals/grounding/  grounding evaluation prompt set
scripts/          maintainer scripts (refresh bundled samples)
tests/            unit, property, contract and regression tests
docs/             quickstart, methodology, data-pack guide, skill guide, solver adapters, assets/ (graphics)

ドキュメント

• クイックスタート
• 方法論
• データパックガイド
• スキルガイド
• ソルバーアダプター
• リリース
• コントリビューション · 変更履歴

ライセンス

• コード： Apache License 2.0。
• データパック： CC BY 4.0。各レコードの元の出典を明記してください。
• コピーレフトのソルバーは、サブプロセスとして実行する別パッケージで提供されます。helionyx-microgridspy （EUPL-1.2）およびhelionyx-sama（AGPL-3.0）です。コアがこれらをインポートすることはありません。

免責事項

Helionyx の結果は、簡略化されたモデル、合成データまたはユーザー提供データ、および古く、未検証の仮置きの料金・コスト前提に基づく実現可能性の事前評価です。エンジニアリング設計、融資可能な発電量評価、財務アドバイス、系統適合性調査ではなく、資格を有するエンジニアによる審査に代わるものではありません。本ソフトウェアは保証や責任を伴わず「現状有姿」で提供されます（Apache-2.0 §7–8）。Helionyx は独立したプロジェクトであり、HOMER Energy / UL Solutions、NREL、NASA、EC JRC、CEB、LECO、Anthropic とは提携関係になく、これらから推奨を受けていません。商標は各所有者に帰属します。一部の機能では、サイトまたは負荷のデータがサードパーティサービスに送信されます。使用前に、免責事項全文をお読みください。