pangea 0.0.42 → 0.0.45

data/lib/pangea/resources/aws_braket_quantum_task/CLAUDE.md

@@ -0,0 +1,188 @@
+# AWS Braket Quantum Task - Architecture and Implementation
+
+## Overview
+
+The `aws_braket_quantum_task` resource manages quantum computing tasks in AWS Braket, Amazon's fully managed quantum computing service. This resource enables running quantum circuits on various quantum simulators and actual quantum processing units (QPUs) from providers like IonQ, Rigetti, and Oxford Quantum Circuits.
+
+## Key Concepts
+
+### Quantum Computing Fundamentals
+- **Quantum Circuit**: A sequence of quantum gates applied to qubits
+- **Qubit**: Quantum bit that can exist in superposition of 0 and 1 states
+- **Quantum Gates**: Operations that manipulate qubit states (H, CNOT, RX, RY, RZ, etc.)
+- **Shots**: Number of times a quantum circuit is executed to gather statistical results
+- **Measurement**: Collapsing quantum states to classical bits
+
+### Braket Device Types
+1. **Simulators**: Classical computers simulating quantum behavior
+   - State Vector (SV1): Full quantum state simulation
+   - Density Matrix (DM1): Includes noise and decoherence effects
+   - Tensor Network (TN1): Efficient for certain circuit structures
+
+2. **Quantum Processing Units (QPUs)**: Actual quantum hardware
+   - IonQ: Trapped ion technology
+   - Rigetti: Superconducting qubits
+   - Oxford Quantum Circuits: Coaxial transmon qubits
+
+## Implementation Details
+
+### Type Validation
+- **JSON Validation**: Ensures action and device_parameters are valid JSON
+- **Shots Limits**: Enforces reasonable limits (1-100,000) for quantum devices
+- **S3 Validation**: Validates bucket names and key prefixes
+- **Cost Estimation**: Calculates estimated costs based on device type and shots
+
+### Quantum Circuit Specification
+Tasks use the JSON-based Amazon Braket Intermediate Representation (IR):
+```json
+{
+  "braketSchemaHeader": {
+    "name": "braket.ir.jaqcd.program",
+    "version": "1.0"
+  },
+  "instructions": [
+    { "type": "h", "target": 0 },
+    { "type": "cnot", "control": 0, "target": 1 }
+  ]
+}
+```
+
+### Device Selection Strategy
+- **Development**: Use simulators for algorithm development and testing
+- **Validation**: Use small shot counts on QPUs for validation
+- **Production**: Use appropriate QPU based on circuit requirements and availability
+
+## Quantum Algorithm Patterns
+
+### 1. Bell State Preparation
+Creates maximally entangled quantum states:
+```ruby
+bell_circuit = {
+  instructions: [
+    { type: "h", target: 0 },           # Hadamard on qubit 0
+    { type: "cnot", control: 0, target: 1 }  # Entangle qubits
+  ]
+}
+```
+
+### 2. Quantum Fourier Transform (QFT)
+Essential for many quantum algorithms:
+```ruby
+qft_circuit = {
+  instructions: [
+    { type: "h", target: 2 },
+    { type: "cphaseshift", control: 1, target: 2, angle: Math::PI/2 },
+    { type: "cphaseshift", control: 0, target: 2, angle: Math::PI/4 },
+    { type: "h", target: 1 },
+    { type: "cphaseshift", control: 0, target: 1, angle: Math::PI/2 },
+    { type: "h", target: 0 },
+    { type: "swap", targets: [0, 2] }
+  ]
+}
+```
+
+### 3. Variational Quantum Eigensolver (VQE)
+For finding ground states of molecules:
+```ruby
+vqe_ansatz = {
+  instructions: [
+    { type: "ry", target: 0, angle: theta_0 },
+    { type: "ry", target: 1, angle: theta_1 },
+    { type: "cnot", control: 0, target: 1 },
+    { type: "rx", target: 0, angle: theta_2 },
+    { type: "rx", target: 1, angle: theta_3 }
+  ]
+}
+```
+
+### 4. Quantum Approximate Optimization Algorithm (QAOA)
+For combinatorial optimization:
+```ruby
+qaoa_circuit = {
+  instructions: [
+    # Initial superposition
+    { type: "h", target: 0 },
+    { type: "h", target: 1 },
+    # Problem Hamiltonian
+    { type: "rzz", angle: gamma, targets: [0, 1] },
+    # Mixer Hamiltonian
+    { type: "rx", angle: beta, target: 0 },
+    { type: "rx", angle: beta, target: 1 }
+  ]
+}
+```
+
+## Best Practices
+
+### Resource Management
+1. **S3 Organization**: Use structured key prefixes for experiments
+2. **Job Tokens**: Group related tasks for batch processing
+3. **Tagging**: Use tags for cost allocation and project tracking
+
+### Performance Optimization
+1. **Circuit Depth**: Minimize circuit depth for better fidelity on QPUs
+2. **Shot Selection**: Balance statistical accuracy with cost
+3. **Device Selection**: Match device capabilities to circuit requirements
+
+### Error Mitigation
+1. **Noise Characterization**: Use DM1 simulator to understand noise effects
+2. **Error Correction**: Implement quantum error correction codes when needed
+3. **Result Validation**: Compare QPU results with simulator baselines
+
+## Integration Patterns
+
+### With ML Pipelines
+```ruby
+# Quantum feature map for ML
+feature_map_task = aws_braket_quantum_task(:qml_features, {
+  device_arn: qpu_arn,
+  action: encode_classical_data_to_quantum_circuit(data),
+  output_s3_bucket: ml_bucket,
+  output_s3_key_prefix: "quantum-features/batch-#{batch_id}"
+})
+```
+
+### With Classical Optimization
+```ruby
+# Hybrid quantum-classical optimization loop
+optimization_task = aws_braket_quantum_task(:vqe_iteration, {
+  device_arn: simulator_arn,
+  action: parametrized_circuit(current_parameters),
+  output_s3_bucket: optimization_bucket,
+  output_s3_key_prefix: "vqe/iteration-#{iteration}",
+  job_token: "vqe-optimization-#{run_id}"
+})
+```
+
+### With Data Processing
+```ruby
+# Quantum data encoding and processing
+data_task = aws_braket_quantum_task(:quantum_encoding, {
+  device_arn: tn1_simulator_arn,
+  action: amplitude_encoding_circuit(dataset),
+  output_s3_bucket: data_bucket,
+  output_s3_key_prefix: "encoded-data/#{timestamp}"
+})
+```
+
+## Security Considerations
+
+1. **Device Access**: Braket devices are accessed via IAM permissions
+2. **S3 Encryption**: Enable S3 encryption for sensitive quantum algorithms
+3. **Result Privacy**: Quantum results may reveal proprietary algorithms
+4. **Access Logging**: Enable CloudTrail for quantum task auditing
+
+## Cost Optimization
+
+1. **Simulator First**: Develop and test on simulators before QPUs
+2. **Batch Processing**: Group tasks to minimize per-task overhead
+3. **Shot Optimization**: Use minimum shots needed for statistical significance
+4. **Device Selection**: Choose most cost-effective device for requirements
+
+## Future Considerations
+
+As quantum computing evolves:
+1. **Fault-Tolerant Computing**: Prepare for error-corrected quantum computers
+2. **Quantum Networks**: Integration with quantum communication protocols
+3. **Hybrid Algorithms**: Increased focus on quantum-classical hybrid approaches
+4. **Industry Applications**: Domain-specific quantum algorithms and circuits

data/lib/pangea/resources/aws_braket_quantum_task/resource.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require 'pangea/resources/base'
+require 'pangea/resources/reference'
+require 'pangea/resources/aws_braket_quantum_task/types'
+require 'pangea/resource_registry'
+
+module Pangea
+  module Resources
+    module AWS
+      # Create an AWS Braket Quantum Task with type-safe attributes
+      #
+      # @param name [Symbol] The resource name
+      # @param attributes [Hash] Braket quantum task attributes
+      # @return [ResourceReference] Reference object with outputs and computed properties
+      def aws_braket_quantum_task(name, attributes = {})
+        # Validate attributes using dry-struct
+        task_attrs = Types::BraketQuantumTaskAttributes.new(attributes)
+        
+        # Generate terraform resource block via terraform-synthesizer
+        resource(:aws_braket_quantum_task, name) do
+          # Set device ARN
+          device_arn task_attrs.device_arn
+          
+          # Set action JSON
+          action task_attrs.action
+          
+          # Set device parameters if provided
+          device_parameters task_attrs.device_parameters if task_attrs.device_parameters
+          
+          # Set output S3 location
+          output_s3_bucket task_attrs.output_s3_bucket
+          output_s3_key_prefix task_attrs.output_s3_key_prefix
+          
+          # Set shots count
+          shots task_attrs.shots
+          
+          # Set job token if provided
+          job_token task_attrs.job_token if task_attrs.job_token
+          
+          # Set tags if provided
+          if task_attrs.tags && !task_attrs.tags.empty?
+            tags task_attrs.tags
+          end
+        end
+        
+        # Return resource reference with available outputs
+        ResourceReference.new(
+          type: 'aws_braket_quantum_task',
+          name: name,
+          resource_attributes: task_attrs.to_h,
+          outputs: {
+            id: "${aws_braket_quantum_task.#{name}.id}",
+            arn: "${aws_braket_quantum_task.#{name}.arn}",
+            status: "${aws_braket_quantum_task.#{name}.status}",
+            output_s3_uri: "${aws_braket_quantum_task.#{name}.output_s3_uri}",
+            created_at: "${aws_braket_quantum_task.#{name}.created_at}",
+            ended_at: "${aws_braket_quantum_task.#{name}.ended_at}"
+          },
+          computed: {
+            device_type: task_attrs.device_type,
+            is_simulator: task_attrs.is_simulator?,
+            is_quantum_hardware: task_attrs.is_quantum_hardware?,
+            quantum_circuit: task_attrs.quantum_circuit,
+            estimated_cost: task_attrs.estimated_cost,
+            output_location: task_attrs.output_location,
+            action_summary: task_attrs.action_summary
+          }
+        )
+      end
+    end
+  end
+end
+
+# Auto-register this module when it's loaded
+Pangea::ResourceRegistry.register(:aws, Pangea::Resources::AWS)

data/lib/pangea/resources/aws_braket_quantum_task/types.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require 'dry-struct'
+require 'pangea/resources/types'
+
+module Pangea
+  module Resources
+    module AWS
+      module Types
+      # Type-safe attributes for AWS Braket Quantum Task resources
+      class BraketQuantumTaskAttributes < Dry::Struct
+        transform_keys(&:to_sym)
+
+        # Device ARN (required)
+        attribute :device_arn, Resources::Types::String
+
+        # Action JSON specification (required)
+        attribute :action, Resources::Types::String
+
+        # Device parameters (optional)
+        attribute? :device_parameters, Resources::Types::String.optional
+
+        # Output S3 bucket (required)
+        attribute :output_s3_bucket, Resources::Types::String
+
+        # Output S3 key prefix (required)
+        attribute :output_s3_key_prefix, Resources::Types::String
+
+        # Shots - number of times to run the quantum circuit (optional)
+        attribute? :shots, Resources::Types::Integer.default(1000)
+
+        # Job token for grouping tasks (optional)
+        attribute? :job_token, Resources::Types::String.optional
+
+        # Tags (optional)
+        attribute? :tags, Resources::Types::Hash.schema(
+          Resources::Types::String => Resources::Types::String
+        ).optional
+
+        # Custom validation
+        def self.new(attributes = {})
+          attrs = super(attributes)
+
+          # Validate shots is positive
+          if attrs.shots && attrs.shots <= 0
+            raise Dry::Struct::Error, "shots must be positive, got #{attrs.shots}"
+          end
+
+          # Validate shots is within reasonable limits for quantum devices
+          if attrs.shots && attrs.shots > 100000
+            raise Dry::Struct::Error, "shots cannot exceed 100000 for quantum devices, got #{attrs.shots}"
+          end
+
+          # Validate action is valid JSON
+          begin
+            JSON.parse(attrs.action)
+          rescue JSON::ParserError => e
+            raise Dry::Struct::Error, "action must be valid JSON: #{e.message}"
+          end
+
+          # Validate device_parameters is valid JSON if provided
+          if attrs.device_parameters
+            begin
+              JSON.parse(attrs.device_parameters)
+            rescue JSON::ParserError => e
+              raise Dry::Struct::Error, "device_parameters must be valid JSON: #{e.message}"
+            end
+          end
+
+          # Validate S3 bucket name format
+          unless attrs.output_s3_bucket.match?(/\A[a-z0-9][a-z0-9\-\.]*[a-z0-9]\z/)
+            raise Dry::Struct::Error, "output_s3_bucket must be a valid S3 bucket name"
+          end
+
+          # Validate S3 key prefix doesn't start with /
+          if attrs.output_s3_key_prefix.start_with?('/')
+            raise Dry::Struct::Error, "output_s3_key_prefix should not start with '/'"
+          end
+
+          attrs
+        end
+
+        # Helper methods
+        def device_type
+          case device_arn
+          when /simulator/i
+            :simulator
+          when /qpu/i
+            :quantum_processing_unit
+          when /sv1/i
+            :state_vector_simulator
+          when /dm1/i
+            :density_matrix_simulator
+          when /tn1/i
+            :tensor_network_simulator
+          else
+            :unknown
+          end
+        end
+
+        def is_simulator?
+          device_type != :quantum_processing_unit
+        end
+
+        def is_quantum_hardware?
+          device_type == :quantum_processing_unit
+        end
+
+        def quantum_circuit
+          @quantum_circuit ||= begin
+            action_data = JSON.parse(action)
+            action_data['braketSchemaHeader']['name'] if action_data['braketSchemaHeader']
+          rescue
+            nil
+          end
+        end
+
+        def estimated_cost
+          # Rough cost estimation based on device type and shots
+          base_cost = case device_type
+          when :quantum_processing_unit
+            0.30 # $0.30 per task for QPU
+          when :state_vector_simulator
+            0.075 # $0.075 per minute for SV1
+          when :density_matrix_simulator
+            0.075 # $0.075 per minute for DM1
+          when :tensor_network_simulator
+            0.275 # $0.275 per minute for TN1
+          else
+            0.00 # Free for local simulators
+          end
+
+          # Adjust for shots
+          shot_multiplier = (shots / 1000.0).ceil
+          base_cost * shot_multiplier
+        end
+
+        def output_location
+          "s3://#{output_s3_bucket}/#{output_s3_key_prefix}"
+        end
+
+        def action_summary
+          action_data = JSON.parse(action)
+          {
+            type: action_data['braketSchemaHeader']&.fetch('name', 'unknown'),
+            version: action_data['braketSchemaHeader']&.fetch('version', 'unknown'),
+            qubit_count: action_data['instructions']&.map { |i| i['target']&.max || 0 }&.max&.+(1) || 0
+          }
+        rescue
+          { type: 'unknown', version: 'unknown', qubit_count: 0 }
+        end
+      end
+    end
+      end
+    end
+  end
+end