Rename investment group input tables to explicit investment_* names (#1621)

* Initial plan

* Rename investment group input tables

Rename group_asset/group_asset_membership to investment_group_asset/investment_group_asset_membership across schema, model building, validation, tests, fixtures, and user docs.

Co-Authored-By: Claude Code (claude-sonnet-4-6) <noreply@anthropic.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Claude Code (claude-sonnet-4-6) <noreply@anthropic.com>

Author: Copilot

docs/src/20-user-guide/20-how-to-use.md

@@ -544,8 +544,8 @@ Groups are useful to represent several common constraints.
 
 In order to define the groups in the model, the following steps are necessary:
 
-1. Create a group file by defining the `name` property and its parameters in the `group_asset` table (or CSV file).
-2. Assign assets to the group by adding entries to the `group_asset_membership` table (or CSV file).
+1. Create a group file by defining the `name` property and its parameters in the `investment_group_asset` table (or CSV file).
+2. Assign assets to the group by adding entries to the `investment_group_asset_membership` table (or CSV file).
 
 #### [Group Investment constraints](@id investment-group-setup)
 
@@ -556,32 +556,37 @@ $\sum_{a \in G} v^{\text{inv}}_a \times \text{coefficient}_a \left\{\begin{array
 i.e., a sum-product of all investment variables listed in the group multiplied by given coefficients related by a "right hand side".
 An example of group investment are the maximum and minimum investment limits for group of investment variables.
 The mathematical formulation of these constraints is available [here](@ref investment-group-constraints).
-They can be achieved using group investment constraints by adding rows in `group_asset` such that:
 
-- Each row in table `group_asset`
+!!! info
+    At the moment, group constraints are only supported for investment variables through `investment_group_asset` and `investment_group_asset_membership`.
+    If you need additional constraints involving other variables, add them manually to the JuMP model as shown in the [Bids tutorial](@ref bids-tutorial).
+
+They can be achieved using group investment constraints by adding rows in `investment_group_asset` such that:
+
+- Each row in table `investment_group_asset`
   - `name` is the name of the group, and unique identifier.
   - `milestone_year` is the year for which the group is defined.
   - `invest_method = true`. This parameter enables the model to use the investment group constraints.
   - `constraint_sense` is either `<=` for maximum and `>=` for minimum.
   - `rhs` is the corresponding value.
-- Each row in table `group_asset_membership`
-  - `group_name` should match `group_asset.name`.
+- Each row in table `investment_group_asset_membership`
+  - `group_name` should match `investment_group_asset.name`.
   - `asset` is the name of the asset.
-  - `milestone_year` should match `group_asset.milestone_year` and `asset.milestone_year`.
+  - `milestone_year` should match `investment_group_asset.milestone_year` and `asset.milestone_year`.
   - `coefficient` should be the capacity value for the investment limit.
 
 !!! warning
-    Notice that only one constraint is created per row in `group_asset`, which means that if both the minimum and maximum investment limits are desired, two rows are required in `group_asset`, one with `constraint_sense = '<='` and one with `constraint_sense = '>='`. In this case, the names of the groups must be different, from instance `ccgt_max` and `ccgt_min`.
-    Similarly, the elements in `group_asset_membership` will need to be duplicated, one for each group.
+    Notice that only one constraint is created per row in `investment_group_asset`, which means that if both the minimum and maximum investment limits are desired, two rows are required in `investment_group_asset`, one with `constraint_sense = '<='` and one with `constraint_sense = '>='`. In this case, the names of the groups must be different, from instance `ccgt_max` and `ccgt_min`.
+    Similarly, the elements in `investment_group_asset_membership` will need to be duplicated, one for each group.
 
 #### Example: Group of Assets
 
-Let's explore how the groups are set up in the test case called [Norse](https://github.com/TulipaEnergy/TulipaEnergyModel.jl/tree/main/test/inputs/Norse). First, let's take a look at the `group-asset.csv` file:
+Let's explore how the groups are set up in the test case called [Norse](https://github.com/TulipaEnergy/TulipaEnergyModel.jl/tree/main/test/inputs/Norse). First, let's take a look at the `investment-group-asset.csv` file:
 
 ```@example display-group-setup
 using DataFrames # hide
 using CSV # hide
-input_asset_file = "../../../test/inputs/Norse/group-asset.csv" # hide
+input_asset_file = "../../../test/inputs/Norse/investment-group-asset.csv" # hide
 assets = CSV.read(input_asset_file, DataFrame, header = 1) # hide
 ```
 
@@ -590,8 +595,8 @@ In the given data, there are two groups: `renewables` and `ccgt`. Both groups ha
 Let's now explore which assets are in each group. To do so, we can take a look at the `asset.csv` file:
 
 ```@example display-group-setup
-input_file = "../../../test/inputs/Norse/group-asset-membership.csv" # hide
-group_asset_membership = CSV.read(input_file, DataFrame) # hide
+input_file = "../../../test/inputs/Norse/investment-group-asset-membership.csv" # hide
+investment_group_asset_membership = CSV.read(input_file, DataFrame) # hide
 ```
 
 Here we can see that the assets `Asgard_Solar` and `Midgard_Wind` belong to the `renewables` group, while the assets `Asgard_CCGT` and `Midgard_CCGT` belong to the `ccgt` group.

docs/src/20-user-guide/54-input-table-schemas.md

@@ -5,7 +5,7 @@ The input data must follow the table schemas below to correctly build a system i
 The schemas below are in [`input-schemas.json`](https://github.com/TulipaEnergy/TulipaEnergyModel.jl/blob/main/src/input-schemas.json). You can also view the schemas after loading the package by typing `TulipaEnergyModel.schema` in the Julia console.
 
 !!! info "Optional tables/files and their defaults"
-    The following tables/files are allowed to be missing: "assets\_rep\_periods\_partitions", "assets\_timeframe\_partitions", "assets\_timeframe\_profiles", "flows\_rep\_periods\_partitions", "group\_asset", "group\_asset\_membership", "profiles\_timeframe". These tables that are allowed to be missing are tables allowed to be empty, i.e., to have 0 rows, during model creation.
+    The following tables/files are allowed to be missing: "assets\_rep\_periods\_partitions", "assets\_timeframe\_partitions", "assets\_timeframe\_profiles", "flows\_rep\_periods\_partitions", "investment\_group\_asset", "investment\_group\_asset\_membership", "profiles\_timeframe". These tables that are allowed to be missing are tables allowed to be empty, i.e., to have 0 rows, during model creation.
     - For the partitions tables/files, the default value are `specification = uniform` and `partition = 1` for each asset/flow and year
     - For the profiles tables/files, the default value is a flat profile of value 1.0 p.u.
     - If no group table/file is available there will be no group constraints in the model

src/constraints/investment_group.jl

@@ -47,18 +47,18 @@ function _append_group_data_to_indices!(connection, cons_table_name)
         """
         WITH cte_group_expression AS (
             SELECT
-                group_asset.name AS name,
-                group_asset.milestone_year AS milestone_year,
+                investment_group_asset.name AS name,
+                investment_group_asset.milestone_year AS milestone_year,
                 ARRAY_AGG(var.id) AS var_assets_investment_ids,
-                ARRAY_AGG(group_asset_membership.coefficient) AS coefficients,
-            FROM group_asset
-            LEFT JOIN group_asset_membership
-                ON group_asset.name = group_asset_membership.group_name
-                AND group_asset.milestone_year = group_asset_membership.milestone_year
+                ARRAY_AGG(investment_group_asset_membership.coefficient) AS coefficients,
+            FROM investment_group_asset
+            LEFT JOIN investment_group_asset_membership
+                ON investment_group_asset.name = investment_group_asset_membership.group_name
+                AND investment_group_asset.milestone_year = investment_group_asset_membership.milestone_year
             LEFT JOIN var_assets_investment AS var
-                ON group_asset_membership.asset = var.asset
-                AND group_asset.milestone_year = var.milestone_year
-            GROUP BY group_asset.name, group_asset.milestone_year
+                ON investment_group_asset_membership.asset = var.asset
+                AND investment_group_asset.milestone_year = var.milestone_year
+            GROUP BY investment_group_asset.name, investment_group_asset.milestone_year
         )
         SELECT
             cons.*,

src/data-validation.jl

@@ -154,7 +154,7 @@ function _validate_no_duplicate_rows!(error_messages, connection)
         ("flow_milestone", [:from_asset, :to_asset, :milestone_year]),
         ("flows_profiles", [:from_asset, :to_asset, :milestone_year, :profile_type]),
         ("flows_rep_periods_partitions", [:from_asset, :to_asset, :milestone_year, :rep_period]),
-        ("group_asset", [:name, :milestone_year]),
+        ("investment_group_asset", [:name, :milestone_year]),
         ("profiles_rep_periods", [:profile_name, :milestone_year, :rep_period, :timestep]),
         ("profiles_timeframe", [:profile_name, :milestone_year, :period]),
         ("rep_periods_data", [:milestone_year, :rep_period]),
@@ -279,15 +279,15 @@ end
 function _validate_assets_in_investment_groups_are_investable!(error_messages, connection)
     query = """
     SELECT
-        group_asset_membership.group_name,
-        group_asset_membership.asset,
-        group_asset.milestone_year,
-    FROM group_asset_membership
-    LEFT JOIN group_asset
-        ON group_asset_membership.group_name = group_asset.name
+        investment_group_asset_membership.group_name,
+        investment_group_asset_membership.asset,
+        investment_group_asset.milestone_year,
+    FROM investment_group_asset_membership
+    LEFT JOIN investment_group_asset
+        ON investment_group_asset_membership.group_name = investment_group_asset.name
     LEFT JOIN asset_milestone
-        ON group_asset_membership.asset = asset_milestone.asset
-        AND group_asset.milestone_year = asset_milestone.milestone_year
+        ON investment_group_asset_membership.asset = asset_milestone.asset
+        AND investment_group_asset.milestone_year = asset_milestone.milestone_year
     WHERE NOT asset_milestone.investable
     """
     for row in DuckDB.query(connection, query)
@@ -301,40 +301,40 @@ function _validate_assets_in_investment_groups_are_investable!(error_messages, c
 end
 
 function _validate_group_consistency!(error_messages, connection)
-    # Check the values in the table `group_asset_membership`:
-    # - `group_name` comes from `group_asset.name`
+    # Check the values in the table `investment_group_asset_membership`:
+    # - `group_name` comes from `investment_group_asset.name`
     # - `asset` comes from `asset.asset`
     _validate_foreign_key!(
         error_messages,
         connection,
-        "group_asset_membership",
+        "investment_group_asset_membership",
         :group_name,
-        "group_asset",
+        "investment_group_asset",
         :name,
     )
     _validate_foreign_key!(
         error_messages,
         connection,
-        "group_asset_membership",
+        "investment_group_asset_membership",
         :asset,
         "asset",
         :asset,
     )
 
-    # Check that the groups created in `group_asset` have at least one entry in `group_asset_membership`
+    # Check that the groups created in `investment_group_asset` have at least one entry in `investment_group_asset_membership`
     for row in DuckDB.query(
         connection,
         "FROM (
-            SELECT group_asset.name, COUNT(group_asset_membership.asset) AS count_group_members
-            FROM group_asset
-            LEFT JOIN group_asset_membership
-                ON group_asset.name = group_asset_membership.group_name
-            GROUP BY group_asset.name
+            SELECT investment_group_asset.name, COUNT(investment_group_asset_membership.asset) AS count_group_members
+            FROM investment_group_asset
+            LEFT JOIN investment_group_asset_membership
+                ON investment_group_asset.name = investment_group_asset_membership.group_name
+            GROUP BY investment_group_asset.name
         ) WHERE count_group_members = 0",
     )
         push!(
             error_messages,
-            "Group '$(row.name)' in 'group_asset' has no members in 'group_asset_membership'",
+            "Group '$(row.name)' in 'investment_group_asset' has no members in 'investment_group_asset_membership'",
         )
     end
 

src/input-schemas.json

@@ -788,7 +788,7 @@
       "type": "VARCHAR"
     }
   },
-  "group_asset": {
+  "investment_group_asset": {
     "constraint_sense": {
       "constraints": {
         "oneOf": [
@@ -817,7 +817,7 @@
       "type": "DOUBLE"
     }
   },
-  "group_asset_membership": {
+  "investment_group_asset_membership": {
     "asset": {
       "description": "One of the assets in this group.",
       "type": "VARCHAR"

src/io.jl

@@ -7,8 +7,8 @@ const tables_allowed_to_be_missing = [
     "flows_profiles"
     "flows_relationships"
     "flows_rep_periods_partitions"
-    "group_asset"
-    "group_asset_membership"
+    "investment_group_asset"
+    "investment_group_asset_membership"
     "profiles_rep_periods"
     "profiles_timeframe"
     "stochastic_scenario"

src/sql/create-constraints.sql

@@ -668,7 +668,7 @@ select
     ga.constraint_sense,
     ga.rhs,
 from
-    group_asset as ga
+    investment_group_asset as ga
 where
     ga.invest_method
 ;

…/inputs/Norse/group-asset-membership.csv …se/investment-group-asset-membership.csvtest/inputs/Norse/group-asset-membership.csv renamed to test/inputs/Norse/investment-group-asset-membership.csv test/inputs/Norse/group-asset-membership.csv renamed to test/inputs/Norse/investment-group-asset-membership.csv

@@ -17,22 +17,22 @@
         DuckDB.query(
             connection,
             """
-            CREATE OR REPLACE TABLE group_asset (name VARCHAR, milestone_year INT, constraint_sense VARCHAR, rhs DOUBLE, invest_method BOOL);
-            INSERT INTO group_asset VALUES ('group1', 2030, '<=', 7700, true);
-            INSERT INTO group_asset VALUES ('group1', 2050, '>=', 3300, true);
-            INSERT INTO group_asset VALUES ('group2', 2030, '==', 1234, true);
-            INSERT INTO group_asset VALUES ('group2', 2050, '==', 4321, false);
+            CREATE OR REPLACE TABLE investment_group_asset (name VARCHAR, milestone_year INT, constraint_sense VARCHAR, rhs DOUBLE, invest_method BOOL);
+            INSERT INTO investment_group_asset VALUES ('group1', 2030, '<=', 7700, true);
+            INSERT INTO investment_group_asset VALUES ('group1', 2050, '>=', 3300, true);
+            INSERT INTO investment_group_asset VALUES ('group2', 2030, '==', 1234, true);
+            INSERT INTO investment_group_asset VALUES ('group2', 2050, '==', 4321, false);
             """,
         )
         DuckDB.query(
             connection,
             """
-            CREATE OR REPLACE TABLE group_asset_membership (group_name VARCHAR, milestone_year INT, asset VARCHAR, coefficient DOUBLE);
-            INSERT INTO group_asset_membership VALUES ('group1', 2030, 'producer1', 3.14);
-            INSERT INTO group_asset_membership VALUES ('group1', 2030, 'producer2', 6.66);
-            INSERT INTO group_asset_membership VALUES ('group1', 2050, 'producer2', 2.51);
-            INSERT INTO group_asset_membership VALUES ('group2', 2030, 'producer1', 0.73);
-            INSERT INTO group_asset_membership VALUES ('group2', 2050, 'producer2', 3.45);
+            CREATE OR REPLACE TABLE investment_group_asset_membership (group_name VARCHAR, milestone_year INT, asset VARCHAR, coefficient DOUBLE);
+            INSERT INTO investment_group_asset_membership VALUES ('group1', 2030, 'producer1', 3.14);
+            INSERT INTO investment_group_asset_membership VALUES ('group1', 2030, 'producer2', 6.66);
+            INSERT INTO investment_group_asset_membership VALUES ('group1', 2050, 'producer2', 2.51);
+            INSERT INTO investment_group_asset_membership VALUES ('group2', 2030, 'producer1', 0.73);
+            INSERT INTO investment_group_asset_membership VALUES ('group2', 2050, 'producer2', 3.45);
             """,
         )